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Information about this Manual 
Review the follcwing itans before you read this publication. - 

The subject of this manual 

This manual is c3esigned to give information required to efficiently use 
WICAT's C compiler. 

The audience for whcm this publication was written 

This manual is written for the advanced programmer using WIO^T's C 
compiler. The information herein presupposes a general knowledge of C, 
and e2q)erience in programming. 

An introductory C text^ The £, £LUQe£f and a general overview of C, Ql h 
Reference Mnual ^ are available from WICAT Systems, Inc. This manual 
presupposses familiarity with the information in those books. This 
publication is not tied to a specific C release. 

Related publications 

The Q Primer ^ part number 188-370 101 A, is an excelloit introduction to 
C for the user who has little or no e^q^erience with C. This manual 
presupposes a knowledge of the information in The £ Primer > or equivalent 
e:q3erience with C. 

C: A Reference Manual s part number 188-370-301 A, is an overview of C. It 
is for those with some knowledge of C. The information in it is not 
specific to a particular C implementation. 



Typographical Conventions Used in this Publication 

Bold facing indicates what you should type. 

Square brackets, [], indicate a function key, the name of which appears 
in uppercase within the brackets. For example, [REIKN] , [CTRL] , etc. 
Braces, {}, indicate a key in the keypad. 

Underlining is used for enphasis. 
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Qiapter 1 
Introduction 



This manual is intended to help the user of WICAT's C compiler. It should 
be used in conjunction with The Q Primer > part number 188-370-101 A, and 
£1, h Reference Manual , part number 188-370-301 A. 

The information contained in this manual covers the implonentation of 
WICAT's C under WMCS and under UniPlus+ System V. Where appropriate^ 
topics are discussed in terms of both WMCS and UniPlusf S^stCTi V. 

However, because information on C under UniPLus+ System V is available in 
the UniPlusf System V documentation, this manual enphasizes C under WMCS. 

Ebr example, chapter 2 covers the compilation process under WMCS and 
UniPlus+ System V. 

Chapter 3 gives hints for successful implementation of WiCAT's C compiler 
for WMCS and UniPlusf Syston V. 

Qiapter 4 is a brief introduction to the C and math libraries. 

Chapter 5 describes WICAT's implanentation of floating-point arithmetic 
in relation to C. 

Chapter 6 gives information about optimization under WICAT's C compiler. 

Chapter 7 is a dictionary of C libraries not available as part of the 

WMCS documentation. Because these libraries are documented in the 

UniPlusf iS^stem V manuals, the/ are provided here specifically for the 
user of C under WMCS. 

Chapter 8 contains the four WMCS C compilation commands. They are 
formatted in the WMCS command-description style. If you are using C under 
WMCS, read these command descriptions. 

If you are using C under UniPlus+ ^stem V, see the cc command 
description in the UniPlu&f Systen V User's Reference Manual (Section IL. 
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Chapter 9 contains information to help the user interface C with other 
languages. 

Chapter 10 offers guidelines for debugging when using the C compiler. 

This manual is written for programmers familiar with C. It presupposes an 
acquaintance with the other two books that are part of the WICAT C 
documentation set, and experience with C. 
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Chapter 2 
The Compilation Process 



Under UniPlus+ System V, C files are oompiled with cc. Documentation for 
cc is in the UniPlus+ System V User's Reference Manual (Section 11^ 

Under WMCS, C files are oompiled with compile. The compile command 
description is in chapter 8 of this manual. 

C Compiler Basses 

Compile under WMCS, and cc under UniPlus+ S^stan V, are the interface to 
the Software Generation System (SGS) . The SGS takes canmand line options 
and C source files, and invokes the passes required to translate a C 
source program to an executable object module. 

Files with a .c extension are assumed to contain C source and follow the 
execution path shown. When more than one source file is specified on the 
command line, each file is run through the execution sequence separately 
(up to the LINKER pass) . At this point, the LINKER combines the created 
object files into a single executable. 
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The following diagram shows the compile process under WMCS and UniPlus+ 
S^stem V: 
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.i's, .k's and .s's are temporary files with names derived from the process identification. 
They are hidden in the WMCS dictionary sys$disk/systmp/ or the UniPlus^ System V 
directory /usr/tmp. 
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Limitations on WIO^'s C Qinpiler 



The size of a C program is limited ty the size of internal data 
structures in the compiler (which cannot be changed by the user) • If the 
program requirements exceed these limits, the compiler can fail. 

Following are limitations of the WICAT C compiler: 

Symbol table 1300 symbols 

Expression tree 500 nodes 

parse stack 150 parameters 

switch 500 cases 

block nesting 30 levels 

A program can also be limited by hardfc/are. Some hardware limitations are 
apparent at compile time, others are apparent only when the program 
crashes. 

These are the hardware limitations for a C program: 

1. The total process size is limited to 2Mtytes (or the size of 
available memory if 2 Mbytes is not available) . 

The process size includes the program's text, data, and run-time 
stack. Because of this, the following declaration of an array 
could fail: 

char bigsucker[100] [100] [100]; 

A recursive function with a large amount of local storage could 
also fail because it causes the stack to grow quickly. 

2. The register-indirect-withr-off set addressing mode is used by the 
compiler. It is used for local variable and parameter references. 
It is limited to 16 bits (-32768 to 32767) . 

However, this addressing mode cannot be used if the number of 
local variables, or the nun±>er of bytes of parameters, exceeds 
32767. 

3. Indirection from a NULL pointer can cause subtle problans. Though 
location is technically part of a program's address space, it 
is a location in RDM. 
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Following are ways of misusing a NULL pointer: 

Reaciing: Reac3ing location returns whatever is at the 
lowest RDM address (a jump instruction). When 
printed the result is garbage. 

For example, the following program prints "cp is 

char *cp = 0; 

printf("cp is %s\A"f cp) ; 

Writing: Although location is not writable, an error is 
not produced. The write is ignored. Therefore, the 
following program segment does not produce a core 
dump, but it does not print "true" either. 

char *cp = 0; 

*cp = 'x*; 

if (*cp = 'x') 

printf ("true\n"); 
Executing: Location contains a jump instruction to a 
destination in the system address space (0x200000 
or greater) . Executing the instruction at 
causes a jump to syston space. However, this is a 
memory violation. The program crashes with the 
program counter in the 0x200000+ range. 
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Chapter 3 
WICAT C ImpiL orientation 



This chapter contains information that will be helpful in the 
implementation of WICAT's C. 

Storage 

There are four kinds of storage: 

1. Auto 

These are local variables. They are allocated on the stack at run 
time when a function is called. Auto variatles in inner blocks 
are allocated when the lexically eiclosing function is entered, 
not when the block is entered. However, optional initialization 
occurs when the block is entered. 

Names appear in the compiler output as offsets from the stack 
pointer as follows: 

-<of f set> (sp) 

2. External 

These are global variables. The compiler allocates space for 
these variables and assigns them the names given by the user, 
preceded fcy an underscore. 

If initialized, the storage is allocated and the value is 
assigned at compile time. If not initialized, space is not 
allocated until load time. Ihen the initial value is zero. 

3. Static 

This is another form of global storage. It is global only to the 
defined function or file. Storage is allocated at compile time 
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whether the variable is initialized or not. Names are not 
exported above the local level and are not visible to the user or 
other SGS utilities. 

4. Register 

Register variables are contained in hardware machine registers. 
They are limited to scalar types. 

There can be up to six data variables ( char/short/ int/long) , four 
pointer variables (e.g., char *) , and four floating-point 
registers. The number of floating-point registers is hardware 
dependent. 

Where the user declares more register variables than there are 
registers, the register modifier is ignored. The mapping between 
the name declared by the user and the register containing it is 
often difficult to compute. 



Storage Sizes 

Following is a list of storage sizes for data t^^s under WICAT's C 
compiler: 

char 8 bits 

short 16 bits 

int 32 bits 

long 32 bits 

float 32 bits 

double 64 bits 

Storage Allocation and Access 

To understand how various classes are allocated and accessed, the format 
of C object files and images must be understood. 
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The follcwing diagrams represent the format of executable files and 
images: 
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Loaded UNIX Image 



Text Segment 



Data Segment 
(initialized trom file) 



"BSS" Segment 
(init to zero on load) 



<HOLE> 



Stack 
(new pages init to zero) 



UNIX Executable File 



Header Information 



Data 
(global/static) 



Text 
(program instructions) 



Symbol Table 



The UNIX executable file format is described in more detail in a. out (4) 
of the UniPlus+ System V User's Manual Sections (2-6) . 

Initialized external and static variables are contained in the data 
segment. Names and locations of these variables are in the symbol table. 
The symbol table also contains the names of uninitialized external 
variables. Locations of the variables are added at link time. 

Storage for auto and register variables is not allocated until runtime. 
The names are only in the code that refereices then. 

When loaded, the data segnent has been e3q>anded to include storage for 
the previously uninitialized data variables. This storage has been 
initialized to zero ty the operating system. Auto variables are created 
on the stack when the lexically enclosing function is entered. Register 
variables are loaded into machine registers when the lexically enclosing 
function is entered. 
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Register Allocation 



The C compiler uses the 68000 's ei^t data registers and eight address 
registers as follows: 

a0=l,d0,dl 

These registers are used to oompute and store tanporary values 
during evaluation of expressions. They are not saved when a 
function is called, so their value is not guaranteed across 
functional calls. 

a2-a5,d2-d7 

These registers are available as user-defined register 
variables. If they are not user-defined, the compiler can use 
then as temporary storage. Ihey are saved at function entry and 
restored at exit so their value is maintained across function 
calls. 

a6 

This is the function call stack frame pointer. It is used as a 
base for locating function parameters and local variables. It 
also serves as a backward link to previous function call stack 
frames, i.e. function calls. 

a7 (sp) 

This is the stack pointer. 

Using the Stack 

The C compiler builds and maintains a stack frame for each active 
function. 

Address register 7 (A7, SP) and address register 6 (A6) have special 
meaning. 

Address register 7 (A7) is the current lowest active address (top) of the 
stack. 

Address register 6 (A6) id a frame pointer that defines a base for 
function parameters and local variables. It also provides a a pointer to 
the previous stack frame. 

Stack frames are manipulated with LINK and UNLK 68000 instructions. 



3-5 



WICAT C ImpLonentation 



Follcwing is a diagram of a function call stack frame: 



SP 
-M(A6) 



-4(6) 
A6 

8(A6) 



N(A6) 



Local Variables 



Old Value of A6 



Return addr to CaUer 



Function Parameters 



In the foregoing diagram, local variables are accessed at negative 
offsets from P£, function parameters are at positive offsets, and the 
previous frame pointer value is at the location pointed to by A6. 

Register variables in functions have no associated stack storage except a 
function parameter. 

If a function parameter is declared as register, it has storage in the 
stack frame allocated ty the calling function. Code is generated by the 
compiler to copy the contents of that location to a register when the 
function is entered. 



The following function is a storage allocation example: 



foo(pl, p2, p3) 
char pi; register int p2; short p3; 



/* Locations: 



V 



{ 



register char 
char al[ll] ; 
static int si 
int a2 = 2; 



*apl = 0; 
= 1; 



/* 
/* 
/* 
/* 
/* 
/* 
/* 



V 
V 



pi: ll(a6) 

p2: 12 (a6) and d7 

p3: 18 (a6) */ 

apl: a5 */ 

al: -11 (a6) to -l(a6)*/ 

si: not on stack */ 

a2: -16 (a6) */ 
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In the foregoing example: 



p2 occupies space on the stack. The compiler generates code to copy 
from the stack location: 12 (a6) to the appropriate register, D7. 

apl does not occupy space on the stack because it is a local 
register variable. The compiler generates code to initialize it. 

The calling function pushes all parameters on the stack in reverse 
order. Therefore, they appear as first parameter (lew address) to 
last parameter (hi^ address) . Scalar parameter types shorter than a 
longword are padded to a longv/ord boundary. 

Ihe local arr^ al is arranged from lowest address (a[0]) to the 
highest address (a [10]) even though local variables are allocated 
from highest to lowest (e.g., a2 occupies a lower address than al) • 

The static variable si occupies no stack storage even though it is 
declared inside the function. It is allocated at compile time in the 
initialized data section of the object file. 

Register variables are allocated starting with d7 and a5 to d2 and 
a2. Tlierefore, parameter p2 is in d7 and local variable apl is in 
a5. 

NOTE: The C optimizer removes LINK and UNLK instructions in 
functions with no local variables. In other words, function 
parameters are accessed as positive offsets, from the stack 
pointer instead of offsets from the new-unacceptable A6. The C 
optimizer can also ranap register variables into scratch 
registers (d0,dl,a0,al) . Read chapter 6 of this manual for 
more information on the C optimizer. 

Signed and Unsigned Scalar Types 

The scalar data types char, short, int, and long can be es^licitly 
declared as signed or unsigned. Without a specification, they are signed. 

Unsigned modifiers affect unary and binary operators as follows: 

Arithmetic operators use unsigned arithmetic (e.g., DIVU rather than 
divs) . 

Logical operators use unsigned comparison (e.g., BLS rather than 
BLE). 

The right shift operation zero-fills instead of sign-extends. 

Implicit or explicit cast operations zero-fill rather than sign- 
extend from shorter types to longer types. 
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WIC3Vr C Features 

The WIOVT C compiler implements extended operations on structures and 
unions. Structures and unions can be assigned, passed as parameters, and 
returned as the result of functions. 

In addition, the WICAT C compiler supports enumeration types (enum) , the 
void storage class, unsigned char and unsigned short data types, and the 
asn assembler escape. 

Also, the keyword list for the C compiler conforms to the proposed ANSI 
standard. Hie keywords "const" and "volatile" are reserved for 
impLonentation of the MSI standard. Attempts to use these keywords 
generates a syntax error from the compiler. Entry has been dropped from 
the keyword list. 

A list of keywords for the C compiler appears in appendix c of this 
manual. 

Temporary Piles 

The C compiler creates a temporary file for internal use. Ihis file is 
used to collect string constants from throughout the source file so they 
can be emitted in a single section. When the preprocessor, compiler, 
optimizer, and floating-point postprocessor are run under cc (UniPlus+ 
System V) or compile (WMCS) , temporary files are used to pass information 
from pass to pass. 

These files are named CCCP<unique ID>. In the foregoing name, unique ID 
represents a number that is unique to the process executing C£ or 
compUg« 

Under UniPlus+ S|ystem V, temporary files are created in the following 
standard, system-wide, temporary directory: 

/usr/tmp 

Under WMCS these files are created in the following standard, syst on- 
wide, temporary directory: 

sy s $di sk/sy stmp 

All tonporary files are deleted when the compile process terminates, or 
when the compile process is interrupted. 
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Chapter 4 
Optimization 



The optimized code produced by the Software Generation System (SGS) is 
not really optimimum code; a better term is improved code. Even though 
the C optimizer doesn't really optimize code (it improves it), the term 
"optimization" will be used throughout this manual since that is the term 
traditionally used to describe the "improving" process. 

Optimization occurs in three parts of the SGS: the compiler , the 
optimizer, and the assembler. Hie optimization performed by the compiler 
and the assembler is done automatically, i.e., it is performed on every 
program and the user cannot turn it off. However, the optimizer is 
turned off by default, and you must specify that the optimizer be used if 
you want those optimizations to be performed. 



OGDipiler (coom) Optimizations 

The C compiler performs optimizations that the optimizer cannot do or 
that are very hard to do. Primarily, these optimizations require some 
source context that is not avail abe in the generated assembly code (e.g., 
types of variables) . Th^ are performed whether or not the optimizer is 
turned on. 

The input for these optimizations is the internal e:q)ression trees 
representing pieces of the program. The output is the assonbly code for 
the program's statements. (The fundamental unit for compiler 
optimizations is a C statonent.) 

The following sections describe optimizations performed by the C 
compiler. 



4-1 



Optimization 

Cbnstant folding 

If the operands of an operator are constants (their value is known 
at compile time) , the operation is performed by the compiler. For 
example, the following two assigment statements generate the same 
code: 

i = 3 * 5; 

i = 15; 



Strength reduction 

If one of the operands of a binary operator is a constant, the 
compiler must generate code to perform the operation. However, it 
can use an instruction that takes less time. 

The following examples shew instructions the compiler may use: 

multiply by power-of-2 uses left shift 

unsigned divide by pcwer-of-2 uses right shift 
some long-by-long multiples uses shifts and adds 



Type reductions 

Short integer types (i.e., char and short) that occur in expressions 
should undergo unary/binary conversion (to longer integer types) 
before the expression is evaluated. These conversions cause shorter 
types to be promoted to int. 

For example, consider the following declarations and statanent: 

int i; short s; char cl, c2; /declarations */ 
i = s * ( cl - c2 ) ; /*statement V 

The preceding statanent should be evaluated as if it were this: 

i = (int)s * ( (int)cl - (int)c2 ); 

Since the most efficient data size for the 68000 is 16 bits (a 
short) while the size" of an int is 32 bits, code can be produced 
that is less efficient than it should be. In an effort to produce 
more efficient code, the compiler uses shorter t/pes whenever doing 
so does not change the value of the expression. 
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Therefore, the statanent i=s* (gl-c2); would be evaluated as 
the follcwing: 

i = (int) ( -s * ( (short) cl - (short) c2 ) ); 

This type of shortening is done for bitwise, logical, and arithmetic 
operators. While the rules for type shortening are complicated and 
the shortening may not always be done, the result will not differ 
from the the result obtained had the usual conversions been applied. 



Optimizer {c2/capt) pptiniizations 

Most optimizations are performed by the optimizer. Processor- independent 
(common tail merging), processor-dependent (register mapping), and WICAT- 
specific (suppressing NOPs following stack probes) optimizations are 
performed by the optimizer. 

The input for the optimizer is the assembly-language program produced by 
the compiler. The output from the optimizer is another assembly-language 
program that should be functionally equivalent to the input program. 

The optimizer uses three fundamental units of optimization: 

A module , the largest unit, corresponds to an entire C function. 

A module contains one or more basic blocks . Each basic block is a 
sequence of assembler instructions that start immediately after a 
label or branch and end with the next branch or label. (Ihe next 
branch or label refers to the next one listed in the program, not 
the next one to be executed.) 

Within each basic block, a moving window of one to three 
instructions is used for peephole optimizations. 

This discussion of optimizer optimizations is divided into the techniques 
used to collect data for the optimization and the optimizations 
themselves. 



Data collection techniques 

Ihe optimizer uses the folloving data collection techniques: 

Flow analysis The basic blocks of a module are linked internally to 
form a flow graph. This graph provides information about the flew 
of execution in a module. One basic block is linked to another if 
control from one falls into the other, or if the second basic block 
is the target of a branch from the first. 
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Live/dead analysis For each instruction in a module^ it is 
determined which registers are referenced and which are set. This 
information is transmitted throughout the module so that at every 
instruction it is kncwn which registers contain values that are 
referenced again after the instruction (live registers) and which 
are not referenced again (dead registers) • 

For data registersr the live/dead information is kept for each 
addressable piece of the register, i.e., tyte, word, or long. Ihe 
live/dead information is not computed for condition codes or memory 
locations. 



Q^imization techniques 

These are the optimizations the compiler performs: 

Unreachable code elimination The flew graph is used to detect basic 
blocks that cannot be reached fcy any execution sequence. The 
optimizer eliminates these blocks. 

In the following example, the basic block that consists of the 
assembly statements for 1 is ranoved: 

register int i, j, k; 
for (i = 0; < 10; i++) { 

if (i > 5) { 

k = j; continue; 

} else break; 

j = i * 3; k += 4; /* 1 */ 

NOTE: This is a trivial example that even the compiler would detect. 

Dead code elimination The live/dead information is used to 
detennine whether the value computed ty each stat orient is used. If 
it is not used and the statement has no side effects (such as 
setting condition codes prior to a test instruction) , it is ronoved. 
The removal of a statement can produce dead code, so the procedure 
is repeated until no more dead code is found. 
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In the following example, the entire loop bo<^ will be eliminated 
because the value of register j is not used so 2 is eliminated, and 
then value of register k is not used so 1 is eliminated: 



register int i, j, k; 




for (i = 0; i < 1000000; i-H-) 


{ 


k = (1 « i); 


/* 1 V 


j = (i + k) & 0xFF; 
} 


/* 2 V 



The loop itself is not eliminated because register i is used each 
time through the loop (even though the loop new does nothing) . 



Redundant branch elimination The flow graph is also used to detect 
and eliminate unconditional branches that are the target of other 
branches and branches to the following statement. In the following 
example, for the code on the left, the unconditional branch to .L2 
at .Ll is removed and the label .LI is moved down to the same 
location as ,L2 as shewn in the code on the right: 





fcne 


.Ll 




• 
<stuff> 


.U: 
.T.3: 


bra 
bra 


.L4 
.L2 


<more stuff > 




beq 


.L2 





bne 


.11 




<:stuff> 


.L3: 


• 
bra 


.L4 


a 

<more 


stuff> 


.T.l: 
.L2: 


. 





.L2: 

The second branch to is also ronoved since .L2 is the label for the 
following statement. 



Common tail merging Pairs of basic blocks are compared from the eid 
back to the beginning to determine if the tails of the blocks are 
the same. (Essentially, blocks are the same if they are lexically 
equivalent.) 

If common tails are found, the common portion is broken out to form 
a new block, and branches to the new block are added at the end of 
the old ones. For more efficient use of space and time, a common 
tail must contain a minimum number of statanents before it is broken 
out. 
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tpop rotation The optimizer attanpts to limit the number of branch 
instructions required in loops because branch instructions use a lot 
of CEU time. For example, the following simple while loop generates 
code with a test at the beginning/ the body of the loop^ and a 
branch back to the test: 

while (i 1= 0) 
f(i); 

The test at the beginning includes a branch that skips the body if 
the condition (i != 0) evaluates false. Iherefore, every pass 
through the loop executes two branch instructions. 

Loop rotation moves the test to the bottom of the loop and reverses 
the sense of the test so that a branch is taken to the beginning of 
the loop if the condition evaluates true. Now, only one branch is 
executed each time through the loop. A second branch before the 
loop jumps to the test, but it is only executed once. 

In the following example, the original loop is shown on the left and 
the rotated loop is shewn on the right: 

•Ll: bra .LI 

tst.l _i .Ll: 

beq .12 move.l _i,-(sp) 

move.l _i,-(sp) jsr _f 

jsr _f addq.l #4,sp 

addq.l #4,sp .Ll: 

bra .Ll tst.l _i 

.L2: bne .L2 



NOTE: The foregoing C code fragnent is an example only. The C 
compiler does not actually generate the code shewn on the left 
since the compiler itself rotates simple loops. 



Register remapping Register variable declarations within functions 
cause an association to be formed between the variable and a 
hardware register. When the association is formed, the previous 
contents of the register must be saved so old value can be restored 
when the function is exited. Tlie optimizer avoids these saves and 
restores register values ty remapping register variables into 
scratch registers that do not need to be saved. 
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In the following example, variable i is assigned to hardware 
register d7 and j is assigned to d6: 

register int i, j; 

i = 1; j = 2; 
if (i = j) 

i = j; 
return i; 

This requires code at the beginning to save the old values and code 
at the end to restore those values. The optimizer detects that the 
scratch registers d0 and dl are not used, and it ronaps the 
references to d7 and d6 to dl and d0. This eliminates all saves and 
restores. 

In the following example, compiler-generated code is shown on the 
left and the optimized code is shewn on the right: 



.L13: 



movon.l 


#$C0,-(sp) 


moveq 


#l,d7 


moveq 


#2,d6 


onp.l 


d6rd7 


fcne 


.U3 


move.l 


d6,d7 


move.l 


d7,d0 


movon.l 


(sp)+,#$C0 



,L13: 



moveq 


#l,dl 


moveq 


#2,d0 


cmp.l 


d0,dl 


bne 


.7,13 


move.l 


d0,dl 



move.l dl,d0 



NOTE: Because d0, dl, a0, and al are the only scratch registers, 
only two data register variables and two pointer register 
variables can be remapped this w^. 

LINK/UNLK removal If a function doesn't have non-register local 
variables, the compiler generates a link instruction in the 
following form: 

link a6,#-0 

However, this serves only to save the old value of a6, thereby 
maintaining the function call linkage. The optimizer eliminates all 
links of this kind, changing references to parameters to offsets 
from the stack pointer instead of offsets from the new invalid a6. 
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Consider this C function: 

f(a,b) 
int a, b; 

{ 

a = b; b = 2; 
return (a); 

} 

The compiler output from the foregoing example is shown on the left 
and the optimized code is shewn on the right: 

link a6,#H3 move.l -4+12 (sp) ,-4+8 (sp) 

move.l 12(a6)r8(a6) moveq #2,d0 

moveq #2,d0 move.l d0,-4+12(sp) 

move.l d0,12(a6) move.l -4+8(sp),d0 

move.l 8(a6),d0 rts 

unlk a6 



NOTE: The foregoing causes a couple of serious side effects: 

Because the stack linkage is broken, debuggers no longer 
give a reliable stack backtrace since they rely on 
tracing the link chain. 

Calling a user-supplied assembly language routine that 
changes the value of the stack pointer can change the 
optimizer-generated references to parameters. The only 
way to prevent this frcm happening is to declare at least 
one non- register local variable. 



NOP su ppression Due to an anomaly in the WICAT monory-management 
unit, it is necessary to generate a NOP instruction following a 
stack probe if the next instruction would modify the stack. 
Normally, this NOP is generated as part of the function-entry 
sequence triggered ty the .entry pseudo-operation. Whenever the 
optimizer expands this pseudo-op, it will generate a NOP only when 
it is needed. Unfortunately, if the optimizer doesn't expand it 
(i.e., the function uses floating-point) the appropriate floating- 
point preprocessor will always generate a NOP. Hence, this 
optimization benefits only functions that do not use floating point. 
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Elimination q^ stack pops Parameters to functions are passed by 
pushing them onto the stack (i.e., decronenting the stack pointer 
and storing the parameter at the location it now points to) , After 
returning from the function call, the parameters are popped (i.e., 
stack pointer incronented) . In many cases, one function call 
immediately follows another. 

In these cases, the first function's parameters are popped (stack 
pointer incronented) and then the second is pushed (stack pointer 
decremented) . Here the optimizer will save time by not bothering to 
pop the first function's final parameter and, instead, overwriting 
it with the first parameter to the second function. 

For example, consider the following segment of C code: 

f(a); 
g(b); 

For the foregoing example, the compiler would generate the code on 
the left and the optimizer would generate the code on the left: 



move. 1 


_a,-(sp) 


move.l 


_a,-(sp) 


jsr 


_f 


jsr 


_f 


addq.l 


#4,sp 


move.l 


--b, (sp) 


move. 1 


_b,-(sp) 


jsr 


-g 


jsr 


-g 


addq.l 


#4,sp 


addq.l 


#4,sp 







In the optimized code, the parameter of function f is not popped 
after the call, rather the following statonent just writes over a 
with b, the parameter to function g. This optimization is performed 
even if the function calls are not consecutive, just as long as both 
function calls are in the same basic block (i.e., there are no 
intervening branches or labels.) 

Peephole Optimizations The broadest class of optimizations are 
those performed on the moving instruction window. Peephole 
optimizations entail analyzing one-, two-, and three- instruction 
sequences and renoving instructions that are not needed, or 
rewriting the sequence into an equivaloit sequence that is faster or 
shorter. There are currently about 50 peephole transformations that 
cover a wide variety of instruction sequences. 
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The following examples show some peephole optimizations. "Uie 
conpiler-generated code is on the left, the optimized code is on the 
right. Comments are given after the semicolons: 



dr.l 


d0 


-> 


moveq #0,d0 


; moveq is faster 


moveq 
and.l 


#-l,d0 
d0,dl 


-> 


<deleted> 


} essentially a NOP 


moveq 
add.l 


#5,d0 
d0,dl 


-> 


addq #5,ril 


; move is not necessary 


sub.w 
cmp.w 
bne 


#l,d0 

#-l,d0 

label 


-> 


dbra d0, label 


; single dbra is shorter 
; and much faster 


move.l 

asr.l 

and.l 


#16, d0 -> 

d0,dl 

#$FFFF,rn 


clr.w dl 
^ap dl 


; the latter is equivalent 
; (though not necessarily 
; as obvious) 



The live/dead information is essential for many of the 
transformations. For example, the third optimization in the 
foregoing example could not be done if some instruction following 
the ADD used d0 (i.e., d0 is not dead after the ADD). Also, the 
first example is not really a NOP since the AND sets condition codes 
that might be required later. Therefore, in order to properly ranove 
the AND, the appropriate condition codes must be dead after that 
instruction. 

It should be noted that the transformations are geared toward code 
produced by the C conpiler and are not intended to be generally 
applicable to all assembly-language programs. In fact, the optimizer 
makes a number of assunptions based on the known b^avior of the 
compiler code generator. For example, the second optimization in 
the foregoing example is not done for the more obvious code sequence 
that follows since the optimizer knows that the compiler will 
generate code to first load -1 into a register: 

and.l #-l,dl 



Assembler (as/wimac) Optimizations 

The final phase of optimization is performed is the assembler. There are 
only two transformations done, both having to do with branch 
instructions. The general technique is known as branch shortening or 
span-dependent optimization. These optimizations are controlled ty the -O 
flag of the assembler. The cq. or compile command passes this flag to the 
assenbler, so this optimization is always done. The input to the 
assembler is a file containing assembly-language modules (corresponding 
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to C functions) . The output is a machine-language file in either OOFF or 
LL format. The unit of optimization is the module (function) . 

On the 68000, there are two types of branches. Both types are relative 
in that the target of the branch is specified as a byte distance from the 
current location. The short branch has an 8-bit displacement, allowing 
targets anywhere from -128 to 127 bytes fron the current location. The 
word branch has a 16- bit displaconent, allowing targets from -32768 to 
32767 bytes away. (Branches requiring offsets greater than 16 bits can 
use the JMP instruction, which takes an absolute 32-bit target.) The 
compiler (and optimizer) always generate the word form of branches. 

In the first optimization, the assonbler determines hew far away the 
target of each branch is and shortens it if the distance to the 
respective target will fit in 8 bits. The assonbler only does this with 
intra-module branches. It does not attonpt to shorten inter-module 
branches since it can make no assumptions about the way the linker will 
order modules in the final output file. 

The second optimization is a side-effect of the first. If the target of 
a branch is the next instruction, the branch instruction is replaced ty a 
NOP. 



How to Get Good Code fron the Software Generation System 

The WICAT SGS produces code that is adequate for most applications under 
most circumstances. There are, however, situations that warrant a little 
extra work to coerce evoi better code from the SGS. There are no set 
rules to be followed; experience and experimentation are the best tools 
in these situations. However, the information in the following sections 
can help you produce better code. 

Do not use register variables indiscriminately 

Remenber that in most cases creating a register variable entails 
saving and restoring the previous contents of the register. 
Typically, if a variable is accessed less than three or four times, 
it is not advantageous to make it a register variable. 

Do not over-declare register variables 

You can have only 4 register pointer variables and 6 register long/ 
int/short/char variables. Declaring more doesn't cause a warning to 
be generated, but the register specification is ignored. If the most 
heavily used pointer is declared as a register after four others, 
performance can be far worse than it would be if it were declared 
after only three others. 
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Don't make functions too long 

Long functions increase the probability that the long form of 
branches will have to be used. It also increases the probability 
that the optimizer will run out of memory attonpting to process the 
function. 



Consider using preprocessor macros instead of simple functions 

For example, a function like the following causes a function call, 
register load, compare, and return from function: 

isthree(arg) register int arg; 

{ 

return (arg=3) ; 

} 

This ocurrs because the following preprocessor macro definition 
requires only a single in-line comparison: 

#define isthree(arg) ((arg)=3) 

However, the in-line nature is not alw^s an advantage. 

For example, consider the first segment of C code as opposed to the 
second segment of C code: 

isnum(arg) register int arg; 

{ 

return (arg=0 arg=l arg=2 arg=3 arg=4 
arg==6 arg==6 arg=7 arg==8 arg=9); 
} 



#define isnum(arg) \ 

((arg)==0 (arg)=l (arg) =2 (arg) =3 (arg) =4 \ 

(arg) =5 (arg) =6 (arg) =7 (arg) =8 (arg) =9) 

With the following invocation, the macro definition generates code 
to evaluate the (rather unusual) expression for each of the 10 
comparisons, whereas 'the function definition requires that the 
expression be evaluated only once with 10 register comparisons: 

isnum(anarray[i+5*3] [j/(int)sin(k)]->field.nutherf ield); 
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Use pre-incrgnent/decrgnent in favor of post-incr anent/decrgnent 

The post-incronent form requires that the appropriate value first be 
copied to a tonporary location, the original incranented, and then 
the old value used from the tonporary copy. In the pre-incronent 
form, the value can be incremented in place, and the new value used. 
Note that there is no differoice in the degenerate case where the 
value is not used (e.g., the statenent ++i; vs. i++;) Another 
exception is when the expression can be mapped into a use of the 
68000 post- increment addressing mode. 

Use char and short integer variables instead of int variables 

Since the natural word size of the 68000 is 16 bits, char (8 bit) 
and short (16 bit) operations are typically much faster than the 
analogous 32-bit operation. Using shorter integers often allows the 
compiler and optimizer to perform type reductions and hence generate 
8- and 16-bit operations. This is extremely useful for 
multiplication and division since the 68000 has no hardware 
instructions for performing 32-bit by 32-bit multiplication and 
division. These operations must be done ty calling runtime library 
functions. Note that this tactic can backfire if no type reductions 
can be performed. In these cases, a large portion of the generated 
code ends up being instructions to promote the shorter operands so 
that 32-bit operations can be used. 



Use pointers rather than indices when looping through arrays 

The 68000 does not have an addressing mode that is well suited to 
general array indexing. As a result, array indexing can be an 
expensive proposition. The following operations typically occur for 
a reference of the form arr^[loopindex] : 

1. Loajd loopindex into a register. 

2. Multiply this register by the size of an array element. 

3. Add the address of array. 

4. Put this value into an address register. 

5. Reference the value ty indirecting off the address register. 

This computation is performed at every iteration of the loop. By 
using a pointer variable, references of the form *arraypointer cause 
the following operations to take place: 

1. Load arraypointer into an address register 

2. Reference the value by indirecting off the address register 

This pointer is incrgnented each time through the loop by simply 
adding a constant (the array-elenent size) . This tactic does not 
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gain you much if the termination condition of the loop still 
involves an array reference (e.g., "arraypointer < 
sarray [maxindex] " ) since the termination condition must be evaluated 
each time throu^ the loop. 

Keep the range of switch statements small and not to o sparse 

The range of a switch statement is the numeric difference between 
the lowest valued case and the highest valued case (excluding the 
default case) . The fastest code that the compiler can generate for 
a switch statement is a jump table. Ihis produces the smallest 
average number of comparisons per case (typically one) . In order to 
use a jump table, the range must be less than 16384 and there must 
be at least four cases. 

An additional constraint is that the range not be too sparse. For 
the compiler, this means that the range must be less than three 
times the number of cases. For example, this prevents a 450-elanent 
jump table from being produced for a switch involving only cases 1, 
2, 3, 4, and 450 since there would have to be at least 150 cases to 
generate one. If, for some reason, you needed a jump table in this 
instance you could "pad it out" by adding 145 cases between 5 and 
450 that did nothing but break. 



Seme Special Tricks 

If speed takes precedence over good taste, there are some tricks that can 
be applied in special cases. 

O ptimizing functions with more register variables than registers 

Ihere are at least three w^s to solve this problem. The most 
acceptable way is to break the function into a number of sub- 
functions. However, if you do not want to incur the function call 
overhead, you could either overload register variables or use inner 
blocks. Overloading simply means declaring a set of generic register 
variables (e.g., register int i; register int *p;) and, by using 
explicit casts, use than in place of many differoit variables. This 
is very non-portable. 

A slightly better technique is to declare register variables inside 
inner blocks within a function. This allows the compiler to use the 
same register in different blocks. 
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For example, the following code allows the compiler to use the same 
address register for cp and sp: 

if (addr & 1) { 

register char *cp = (char *)addr; 



addr-H-; 

} 

if (addr & 2) { 

register short *sp = (short *)addr; 



addr += 2; 

} 



Generating Special Instructions and Addressing Modes 

DBRA. instruction If you have a loop in which the loop index serves 
only to control the number of iterations of the loop, it can be 
coded in a special way to allow the optimizer to generate a EBRA 
instruction. For example, consider the following loop: 

int i; 

for (i = 0; i < END; i++) 

<some-stuf f-not-using-i > ; 

If END < 32768, the foregoing code can be rewritten as the 
following : 

register short i; 
i = END - 1; 
do { 

<some-stuf f -not-using-i> ; 
} while (— i i= -1); 

Q!W instruction When comparing bytes of data, the compiler 
generates a O^PM instruction for an if statement of the following 
form if pi and p2 both point to objects of the same size (char/ 
short/int/long) and both pointers are in registers: 

if (*pl-H- = *p2++) 
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PPSt-lncpgnent .sn^ pi:e-<aecFernent addressing modes Expressions 
involving references of the following form, where rp is a register 
variable (char/short/int/long) , produce instructions using post- 
increment and pre-decrement addressing modes: 



*rpH- 
* — rp 



Speeding Up Arithmetic Operations 

In instances where you cannot shorten the types of variables (as 
described earlier) because the range of a variable is greater than 8 
or 16 bits, it is still possible in many instances to gain an 
advantage. Consider the following example, where there is a 
frequently used arithmetic statement in which the majority of the 
operand values are less than 8 or 16 bits: 

register int il, 12; 
for (il = 0; il < 50000; il++) 
12 = il / 33; 

You can try inserting a value test combined with an explicit cast to 
force a shorter operation when appropriate: 

for (il = 0; il < 50000; il++) 
if (il < 32768) 

12 = (short) il / 33; 
else 

12 = il / 33; 

In the foregoing example, the added cost of the test is 
insignificant compared to the time saved by converting the call to 
the runtime 32-bit division to a single hardware division 
instruction. In other situations, the added cost may exceed the 
savings. Only experimentation wjll tell. 



Improving array access and pointer arithmetic 

As mentioned earlier, using pointers to access array elanents is 
typically more efficient than indexing. Ihere are also some other 
special cases that can be improved when indexing is unavoidable. If 
space is not a big concern, array elonent definitions can be padded 
to a size that is a power of 2. Iliis allows the compiler to generate 
a simple shift (as opposed to a long multiply or a series of shifts 
and adds) when selecting an array element. 
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Consider the following section of C code: 

struct s { 

int type; 

char data [26]; 
In- 
struct s sarray[10]; 

struct s *getpointer(ix) 
int ix; 

{ 

return (&sarray [ ix] ) ; 

} 

The foregoing example generates the following eight- instruction 
sequence to compute the return value: 



move. 1 


8(a6),d0 


add.l 


d0,d0 


move.l 


d0,rn 


add.l 


d0,d0 


sub.l 


d0,dl 


asl.l 


#3,d0 


add.l 


dl,d0 


add.l 


#_sarray,d0 



Adding two fcytes of padding to the structure definition (to bring 
the size to 32 bytes) generates the following three- instruction 
sequence : 

move.l 8(a6),d0 
asl.l #5,d0 
add.l #_sarray,d0 

Padding also benefits pointer addition (since that is what array 
indexing really is) . It does not directly help pointer subtraction 
however. For example, the compiler implonents the following array 
by subtracting the two pointers and then dividing by the size of an 
elonent: 

getindex(sp) 
struct s *sp; 

{ 

return (sp - sarray) ; 

} 

The compiler generates a call to the long division routine 
regardless of padding. A right shift is not used because the 
pointers are considered signed. A DIVS instruction cannot be used 
since the quotient might be greater than a word (i.e., the array has 
more than 32767 elenents) , which would cause an overflow with DIVS. 
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When using padding, we can force a right shift ty rewriting the 
function as: 

getindex(sp) 

struct s *sp; 
{ 

return(( (unsigned int)sp - (unsigned int)sarraY) 
/ sizeof (struct s)); 
} 

Fast data coi^ina/ccmDarison 

One of the most common operations in which generated code quality 
has a major impact is copying or comparing blocks of data. As might 
be expected, there are numerous obvious and non-obvious ways to 
perform these functions. For large blocks of data, the best way is 
probably to use the standard library functions that are written in 
assonbly language and have been highly optimized for the best 
performance. IVo such routines are moncpy and mencmp . Under UNIX, 
these routines are documented in memory (3C) of the UniPlus-f Syston V 
User's Reference Manual( Sections 2-6) . 

As usual, there is a trade-off point at which the overhead of the 
function call outweighs the benefits. This point is at about 16 
bytes. For 16 bytes or less, it is often worthwhile to copy/compare 
data in-line. 

The following examples show four possible ways to define a macro to 
copy c bytes from f to t: 

#define aopy0(f,t,c) \ 

{ register int n; for (n = 0; n < c; n++) t[n] = f[n]; } 

#define CDPYl(f,t,c) \ 
memcpy(t,f,c) 

#define G0PY2(f,t,c) \ 

{ register short n = c-1; register char *fp = f , *tp = t; \ 
do *tpH- = *f pH-; while (— n != -1) ; } 

#define (DPy3(f,t^ \ 

{ struct hack { char space [FIXEDSIZE] ; } hack; \ 
*( (struct hack *)t) = *( (struct hack *)f); } 

CX)PY0 is the approach a naive user might first try. Ihough simple, 
it takes easily twice as long as the next slowest method when 
copying 16 bytes. GOPYl is a call to the library routine and, for 
16 bytes, takes nearly twice as long as G0PY2. G0PY2 is probably 
the best code that you can get for byte-by-byte copies. But its 
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speed is highly dependent on having the three register variables 
actually in registers. It also limits the count to 65536 since it 
uses a short counter. 00PY3 is a very special case that requires 
the copy size always be the same and known at compile time. It also 
requires that both the to and from buffers be on an even-tyte 
boundary. ODPYS coerces the buffers into structures so that the 
compiler generates in-line code to do a structure copy. it more 
than twice as fast as aOPy2 and almost 20 times faster than GOPY0 
for a 16-fcyte copy, 

For comparing c characters of two buffers f and t (setting r to one 
if equal, zero if not) , you can define the following analogous 
routines : 

Idefine CMP0(f,t,Crr) \ 

{ register int n; \ 

for (n = 0; n < c; n-H-) \ 

if (t[n] i= f[n]) break; \ 
r = (n == c) ; } 

#define att>l(f,t,c,r) \ 

r = (m€marip(t,frC) = 0); 

#define CMP2(f,trC,r) \ 

{ register short n = c-1; register char *fp = t, *tp = t; \ 
do if (*tpH- i= *fpH-) break; while (— n 1= -1); \ 
r = (n = -1) ; } 

#define CMP3(frtrC,r) \ 

{ register int *ipl = (int *)f, *ip2 = (int *)t; \ 
r = 0; if (*ipl-H- = *ip2-H-) if (*ipl-H- = *ip2-H-) \ 
if (*ipl++ == *ip2-H-) if (*ipl = *ip2) r = 1; } 

The macro that is significantly difference is CMP3, which is 
approximately equivalent to what the compiler might do if there was 
such a thing as structure comparison. It has the same restrictions 
as CDF5f3. For 16-byte comparisons, in the best case where the first 
byte differs, there is very little difference between the three in- 
line versions. The function call version takes about twice as long. 
In the worst case where both buffers are equal, the times are about 
the same as those of the copy macros. 
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cautions about optimizing 

The C optimizer was intended only to improve code generated from the C 
compiler. For this reason, attonpting to optimize hand-ooded assenbly or 
interfacing hand-coded assembly to optimized code is likely to cause 
problems. If you try to do this, you should be aware of the following 
items: 

The peephole optimizer will miss many "obvious" optimizations 
because it assumes the compiler never generates them. 

Mar^ peephole optimizations can be performed only if the condition 
codes are dead following the window in question. Currently, true 
live/dead analysis is not performed on condition codes. To determine 
if the condition codes are dead following a window, it merely checks 
to see if the next instruction uses them. If not, it assumes they 
are dead. 

The optimizer assembly language parser is not complete. It 
recognizes only instructions, addressing modes, and pseudo-ops 
produced by the compiler. Many unrecognized constructs are just 
copied to the output file when they are encountered. Ihis creates 
problems due to the fact that recognized instructions are 
internalized and output at one time at the end of a function. The 
resulting output for a function is thus all unrecognized code for a 
function followed by the optimized body of the function. 

Assembly code in asm statements is not handled well. Currently, the 
optimizer has no way of differentiating between code from asm 
statements and code produced by the compiler. Hence, it attempts to 
optimize it. Most times this works, but sometimes it messes up badly 
(typically because the optimizer assembly language is incomplete) . 

There is no way of selectively choosing which optimizations are 
performed on a function or even a file. 
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El oa ting-point 



WICAT's floating-point arithmetic conforms to a subset of the proposed 
IEEE standard for binary floating-point arithmetic. 

Wia^T's software emulation does not support such features as denormalized 
operands, extended precision, selection of rounding modes, NaN's, and 
full exception handling. The different floating-point hardware types 
conform to this standard in varying degrees. 

Hoir the C Qmpiler Handles floating-point 

The C compiler generates pseudo-code for all floating-point operations. 
This enables programs to use floating-point without the compiler having 
details of each kind of hardware. One pseudo-code statonent (one line) is 
generated for each floating-point operation. The statonent indicates the 
operation to be performed, and the operands to use (source and 
destination) . 

Each type of floating-point hardware has a preprocessor. The software 
emulation also has a preprocessor. These floating-point preprocessors 
convert the pseudo-code to assonbly source statonents. The preprocessor 
generates the assanbly code to perform the indicated operation on its 
type of hardware. Also, a hardware preprocessor that is not hardware 
dependent converts pseudo-code to subroutine calls where the subroutine 
performs the indicated operation. 

For information on selecting a floating-point preprocessor under UniPlus+ 
System V see cc in the UniPlu&f System V Usee's laanual (Section H. 

For information on selecting a floating-point preprocessor under WMCS see 
the compile command description in chapter 8 of this manual. 
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Eloatina-point Under WMCS 

Under WMCS you can bind your program to a floating-point hard/are by 
using its preprocessor at compile time. 

Also, you can use the hardware- independent preprocessor to choose 
the software emulation, or the specific hardware at run time. This 
can be done because the libraries that support the software 
onulation, or the hardware, are not linked into the program's 
executable image at compile time. 

The libraries are in shared memory and become part of your program 
during its execution. They are put into shared memory using the 
fpmar comroand (Refer to the fpmqr command description in the WMCS 
User's Reference Manual) . 

The C language startup routines are autcmatically linked into your 
program. Also, they execute before the first statement of your 
program and connect it to the floating-point library in shared 
monory. 

Floatina-p oint Under UniPlus-f S^^stgn V 

Under UniPlus+ System V you can bind your program to a floating- 
point hardware by using the preprocessor for the hardware at compile 
time. 

The hardware- independent preprocessor binds your program to the 
software floating-point emulation. 

The choice of hardware or software cannot be made at run time. 

The library that supports the software onulation, or the hardware, 
is linked into your program's executable image at compile time. 

Getting the Best Peif onnance 

Following are some general guidelines for getting the best performance 
from floating-point operations. 

Choosing the FLoatina-ooint Preprocessor 

Hardware is faster than software, although the difference in speed 
depends on which operation you are doing and which hardware you are 
using. 

Under UniPlus+ System V your program uses hardware if you compile it 
using the hardware preprocessor. 
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Under WMCS you get best performance by compiling your program with 
the hardware preprocessor. If you use the hardware independent 
preprocessor, and choose the hardware at run time, performance is 
not as good. The code generation is less efficient due to the 
indirectness of subroutine calls and parameter passing. 

C Qgt imiz^c 

■Hie C optimizer makes code generated ky the C compiler more 
efficient. It also optimizes floating-point pseudo-code. 

Because the C optimizer does not recognize differences in hardware, 
some of the pseudo-code optimizations can degrade the program's 
performance on some hardware. 

Your program will probably perform better if it is compiled using 
the C optimizer. However, try it both ways to find which w^ gives 
you best performance. 

Flc>atinq-pQint figgi,ste^;s 

If your floating-point hardware has general-purpose floating-point 
registers, declare floating-point variables as register float or 
register dDubLe to improve performance. 

The first four floating-point registers are reserved as scratch 
registers for the compiler and floating-point preprocessor. The next 
four floating-point registers are available to be used for register 
declarations. 

If your hardware has more than eight registers, only the first eight 
are used. 

The maximum number of useful register declarations is four. 

If your hardware does not have floating-point registers, using 
register declarations degrades performance. 

Operations on floats (single precision) are faster than operations 
on doubles (double precision) . The difference in speed depends on 
whether you are using hardware or software, which hardware is being 
used, and what operation is being performed. 

However, the C language is designed to pronote all calculations to 
double precision. Even if you declare all your floating-point 
variables as float, most calculations are still done in double 
precision. Once calculations are complete, a conversion is performed 
on the result. This converts it to a float. The WICAT C compiler 
makes one exception to this. 

5-3 



Floating-point 



If you use the +=, -=, *=, or /= oprators on float operands, the 
calculation is done in single precision, 

C is also defined to promote all float parameters passed to 
subprograms to double precision. Therefore, a single precision sin, 
cos, exp, sqrt, etc, cannot be computed. The computation is done in 
double. The result is converted to single, 

floating-point Format 

The storage formats for floating-point values conform to the proposed 
IEEE Standard for binary floating-point arithmetic. All values are 
normalized. 

Following is a diagram of a float storage format: 

32 bits total 
1 bit 8 bits 23 bits 



s 


EXP 


F 



31|30 



23|22 

\ 



01 



binary point 



In the foregoing diagram ^ is sign (0=positive, l=negative) , exp is 
biased exponent (true exponent is biased ejqxjnent - 127) , and i is binary 
fraction, 

The float storage format is normalized with an implied 1 bit preceding 
the binary point. 

The float storage format is interpreted (converted to decimal) as (s) l,f 
X 2" (exp-127) , 

It has 6-7 significant decimal digits, and its approximate range is 
8.4e-37 <= X <=3.4ef38. 
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Following is a diagram of a double storage format; 



1 bit 11 bits 



64 bits total 

52 bits 
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binary point 



In the foregoing diagram ^ is sign (0 = positive, 1 = negative) , exp is 
biased exponent (true exponent is biased exponent - 1023) , and j£ is 
binary fraction. 

The double storage format is normalized with an implied 1 bit preceding 
the binary point. 

The double storage format is interpreted (converted to decimal) as (s) 
l.f X 2" (exp-1023) . 

It represents 15 to 16 significant decimal digits, and its approximate 
range is 4.2e-307 <= x <=1.8e+308. 

Pollcwing is a table of reserved floating-point values: 

Float Double 

zero 



+0 00000000 
-0 80000000 



infinity +oo 7FFFFFFF 
-oo FFFFFFFF 



00000000 00000000 
80000000 00000000 

7FFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF 
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Exception Handling 

Pour types of floating-point exceptions are supported: 

1, Underflow occurs when the result of a calculation is too small to 
be represented. 

2. Overflow occurs when the results of a calculation is too large to 
be represented, 

3, Divide-by-zero occurs when you attempt to perform a division 
operation with a denominator of zero. 

4. Illegal operation occurs when you attempt to do a mathematically 
undefined operation (taking the square root of a negative 
number) . 

Each of the foregoing exceptions has a standard default. A default result 
is returned if an error occurs and the exception is masked (the exception 
is turned off because the programmer does not want to know the error 
occurred) , 

The default results are used as operands in subsequent calculations as 
normal results would be. For example, a value of infinity generated due 
to an attempt to divide ty zero can be propagated through subsequent 
calculations in a program. If the value is output, it shows up as 
approximately 1.79ef308. This is the largest number representable in 
double precision. 

Underflow returns zero, overflew returns infinity, and divide-by-zero 
returns infinity when the software enulation exceptions are masked. 

Illegal operation has no default result because it cannot be masked. 

If you are using floating-point hardware, consult the hardware 
documentation to see what exceptions are supported, whether they can be 
masked, and what default results are returned. 

Exception Handling under UniPlus+ Systgn V 

If an exception occurs and SIGFPE has a signal handler defined, the 
SIGFPE signal is generated and caught by the handler. The handler 
does nothing useful for floating-point. The handler cannot return 
its own default result and continue processing. 

The startups automatically define a handler for SIGFPE for the 
process. However, the definition can be deleted, or the defined 
handler can be replaced by a user handler once inside the program. 
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The default handler causes a core dump with the following message: 

Floating exception — core dumped 

The _errno variable is set to ERAN3E. 

If no handler is defined, all exceptions that can be masked are 
masked, default results are generated, and processing continues. You 
are not informed if error conditions occur. 

Exceptions cannot be selectively unmasked from a C program. 

The matherr(3M) routine for handling math errors is not supported. 

Exception Handling under WMCS 

Under WMCS exceptions that can be masked (for software or hardware) 
are masked. In other words, when a maskable exception occurs, the 
standard default result for that condition is returned. You are not 
informed that the error has occurred. 

Exceptions cannot be unmasked from a C program. 

Debugging Floating-point Programs 

A floating-point operation shows up in the assanbly source code produced 
by a floating-point preprocessor in two ways: 

It can be a jsr (subroutine call) to a function name that has no 
underscore. In this case, it typically has a math operation within 
the name (e.g. , jsr addSddxd, jsr divf, jsr sin). 

When a hardware floating-point preprocessor is used, the operation 
can be a move (moves data) , or a tst to an address from 0x2000 to 
0x3fff (the address range is the user process into which the 
hardware is mapped) . The tst compares against , but for hardware 
floating-point, it usually accesses a location to cause an 
operation. 

If you wish to determine what operation is taking place, get a listing of 
the compiler output prior to the floating-point preprocessor pass. Use 
the £c command with the --K option under Uniplus+ System V, and the 
compile command with the :nofpreprocess switch under WMCS. This allows 
you to look at the pseudo-code. 

If you are using floating-point hardware that has registers, neither adb 
nor WIBUG can display or modify the contents of the registers. 

The debuggers are able to input and output IEEE- format single-and double- 
precision numbers. Refer to the WIBUG or adb documentation for details. 
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Debugging floatinq-TX>int programs under UniPlus+ gystan v 

Floating-point routines called fcy jsr instructions are linked into 
your program like other routines. Their symbols appear in adb. You 
can trace through them like any other routine. 

Debugging floatiTig-point programs under WMCS 

Because you can choose the software enulation or a floating-point 
hardware at runtime, you should be aware of the following when 
debugging under WMCS: 

If no libraries, or the wrong libraries, are in shared memory, 
one of the following error messages appears when you try to run 
your program: 

Cannot share directory 

Required hardware floating-point not present 

These errors come from the C startups when they try to connect 
the program to shared memory. 

To avoid this, use fpmgr to put the correct library into shared 
monory. Then, run your program again. 

The symbols for floating-point routines have values in the 
address range 0x1000 to 0xlfff , 

The symbols are entries in a jump table. The value at that 
location in the jump table is the starting address of the 
routine. 

For example, if the value of symbol addSddxd is 0x1008, the 
value stored at location 0x1008 is the starting address of 
addSddxd. It mi^t be something like 0xlfa448. 

The syn±)ol for the floating-point routine name is associated 
with an address in the jump table (not with the starting 
address of the routine) . When you trace through the routine, 
addresses in floating-point routines are not displayed as 
offsets from the routine name. 

Floating-point routines reside in address ranges 0x2000 to 
0x3fff , and 0xlfa000 to 0xlfefff in the process space. 

A breakpoint at a floating-point routine cannot be set until 
the startups have executed. Those routines are not part of your 
process until the startups put them there. If you try to set 
the breakpoint before the startups execute, WIBUG returns a 
monory violation. 
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Get past the startups fcy typing xr jnain. Then set your 
floating-point breakpoint when you have reached _inain. This 
works much better. 

Breakpoints cannot be set inside floating-point routines 
because the code in shared monory is write-protected. If you 
attempt to set breakpoints inside floating-point routines, 
WIBUG gives a memory violation. 

FLoating^-poiixt Librciries 

Following are the floating-point libraries under UniPlus+ Systan V: 

/lib/libc.a software enulation floating-point routines 

/usr/lib/libc-skyl.a SKY hardware floating-point routines 

/usr/lib/libc-ffpl.a FFP hardware floating-point routines 

The floating-point libraries under WMCS are referenced ty the f pmgr 
command when it puts the routines into shared menory: 

/sysexe/1 ib2init.exe software enulation floating-point 

routines 

/sysexe/skylinit.exe SKZ hardware floating-point routines 

/sysexe/f fplinit.exe FFP hardware floating-point routines 
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C Libraries 



The C libraries are collections of object files, which contain the object 
code for one or more useful functions. When a C program (an object 
module) is linked fcy LL or Id to one of these libraries, an object file 
containing a referenced function is linked with the program. Both WMCS 
and UniPlus+ System V have several standard libraries with which to work. 

The C Library 

The C library contains the standard Input/Output routines, system call 
entry points for UniPlus+ ^stem V, string manipulation routines, and 
floating-point access routines. There is a version of this library for 
each floating-point type. 

The C library is searched fcy default if the linker is invoked through £c 
or compile . 

These are the C library files under UniPlus+ Syston V: 

/lib/libc.a version with software FP (default) 

/usr/lib/libc-skyl.a version with SKY FP support 

/usr/lib/libc-ffpl.a version with FFP FP support 

/usr/lib/libc-nofl.a version with no FP support 

These are the C library files under WMCS: 

sys$disk/comlib/libc.lib version with FP support (default) 

sys$disk/comlib/libcnofp.lib version with no FP support 
sys$disk/comlib/libcl00.1ib version with FP support and 

ability to have 100 files open 

simul taneously 

The C library under WMCS has no hardware-specific versions. 
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The math library contains trigonometric, square root, and logarithmic 
functions. 

Under WMCS, the :libraries=litan a/itch must be used to access the math 
library. The library file is SYS$DISK/O0MLIB/LIBM.LIB. 

The Math Library under UniPlus+ Systan V 

Under UniPlusH- System V, the -Im option must be specified with the 
cc command to access the math library. The library file is /usr/lib/ 
lilsn.a. 

Refer to section 3 of the UniPlusf System V User's IJanual (Sections 
2-6) for information on additional libraries under UniPlus+ Syston 
V. 

Also, profiled versions of many of the libraries are available under 
UniPlus+ S^stan V. Every routine (function) in a profiled library 
includes code to" count the calls made to the function (i.e., each 
function that was conpiled with the -p option of ££) . 



6-2 



Chapter 7 
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The C library routines contained in this chapter are for the user of C 
under WMGS. They are derived from the UniPlus+ Systan V documentation and 
have been modified slightly for the WMCS user. 

Each entry in this dictionary is based on the format used in the UniPlus+ 
system V documentation. 

The following sections are used. 

Name gives the name(s) of the routine (s) described under this entry 
and gives a very brief description of it/then. More than one 
routine is often described with one entry because the routines are 
so similar. The dictionary entry for a routine tells where a 
routine is described. (The index also lists where a routine is 
described. ) 

Synopsis shews how a routine is set up. It shows the include files 
needed, if ars^, and shews hew the routine itself is declared. These 
are not lines you type in your program (except the include line) , 
but show the way the routine itself is progrsnnned. 

Description describes in more detail the routines listed in the Name 
section. 

Example gives an example where appropriate. 

Files lists the files the routine (s) might use. 

See also refers to related routines. 

Diagnostics discusses diagnostic indications that can be produced. 

Warnings points out potential problems. 
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Bugs lists kncwn bugs and deficiencies, Sonetimes the suggested fix 
is also listed. 

The user of C under UniElus+ Syston V should consult sections 2 and 3 of 
the UnigLus+ System Y. User's Reference I^jqusI (Sections 2-^) . 
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Name 

a641, 164a - convert between long integer and base-64 ASCII string 

long a641 (s) 
char *s; 

char *164a (1) 
long 1; 

DESCRIPTION 

These functions are used to maintain numbers stored in base-€4 ASCII 
characters. This is a notation by which long integers can be represented 
by up to six characters; each character represents a digit in a radix-64 
notation. 

The characters used to represent digits are . for 0, /for 1, through 9 
for 2-11, A through Z for 12-37, and a through z for 38-63, 

A641 takes a pointer to a null-terminated base-64 representation and 
returns a corresponding long value. If the string pointed to by s 
contains more than six characters, a641 will use the first six, 

L64a takes a long argument and returns a pointer to the corresponding 
base-64 representation. If the argument is 0, 164a returns a pointer to 
a null string. 



BUSS 

The value returned by 164a is a pointer into a static buffer, the 
contents of which are overwritten by each call. 
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Name 

abs - return integer absolute value 



Synopsis 



int abs (i) 
int i; 



Description 



Abs returns the absolute value of its integer operand. 



Bugs 



In ta/o's-complement representation, the absolute value of the negative 
integer with largest magnitude is undefined. Seme implementations trap 
the error, but others ignore it. 



See Also 
floor 
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acos 



NZ^ME 


sin, oos, tan, asin, eicos, a.tan, atan2 - 


■ trigonometric functions 


SYNOPSIS 



See trig 
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asm 



NZ^ME 

asin, cosr tanr sirir aoos, atan, atan2 - trigonometric functions 

SYNOPSIS 
See trig 
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atari 



NAME 

sin, cx)Sf tan, asin, ac»s, atan, atan2 - trigonometric functions 

SYNOPSIS 
See trig 
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bessel 



mm 


j0, jl, jn, 


y0f 


yi/ 


yn - 


- Bessel 


functions 


SYNOPSIS 



#include <iiath.h> 

double j0 (x) 
double x; 

double jl (x) 
double x; 

double jn (n, x) 
int n; 
double x; 

double y0 (x) 
double x; 

double yl (x) 
double x; 

double yn (n, x) 
int n; 
double x; 



DESCRIPTION 



J0 and jl return Bessel functions of x of the first kind of orders and 
1 respectively, Jn returns the Bessel function of x of the first kind of 
order n. 
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SEE ALSO 



exec(2) • 
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NAME 



brk, sbrk - change c3ata segment space allocation 



SYNOPSIS 



int brk (endc3s) 
char *endds; 

char *sbrk (incr) 
int incr; 



DESGRIETIO^ 



Brk and sbrk are used to change (^namically the amount of space allocated 
for the calling process's data segment; see exec (2) . The change is made 
by resetting the process's break value and allocating the appropriate 
amount of space. The break value is the address of the first location 
beyond the end of the data segment. The amount of allocated space 
increases as the break value increases. The newly allocated space is set 
to zero. 

Brk sets the break value to endds and changes the allocated space 
accordingly. 

Sbrk adds incr bytes to the break value and changes the allocated space 
accordingly. Incr can be negative, in which case the cmount of allocated 
space is decreased. 



RETURN VALUE 

Upon successful completion, brk returns a value of and sbrk returns the 
old break value. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 
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bsearch 



NOTES 



■The pointers to the k^ and the element at the base of the table should 
be of type pointer-to-elenent, and cast to type pointer- to-character. The 
comparison function need not compare every tyte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 
Although declared as type pointer-to-character , the value returned should 
be cast into type pointer-to-element. 



SEE ALSO 



1 search, hsearch, qsort, t search 
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NAME 

bsearch - binary search 



SYNOPSIS 



tindude <search.h> 

char *bsearch ((char *) key, (char *) base, nel, sizeof 
(*key), ccmpar) 
unsigned nel; 
int (*canpar) ( ); 



DESCRIPTION 

Bsearch is a binary search routine generalized fron Knuth (6.2.1) 
Algorithm B. It returns a pointer into a table indicating where a datum 
may be found. The table must be previously sorted in increasing order 
according to a provided comparison function. Key points to the datum to 
be sought in the table. Base points to the element at the base of the 
table. Nel is the number of elements in the table. Gompar is the name of 
the comparison function, which is called with two arguments that point to 
the elemoits being compared. The function must return an integer less 
than, equal to, or greater than zero according as the first argument is 
to be considered less than, equal to, or greater than the second. 



DIA3N0STICS 

A NULL pointer is returned if the key cannot be found in the table. 
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ceil 



MME 

floor, ceil, fmod, fabs - floor, ceilingr remainder, absolute value 
functions 



S"aCPSIS 
See floor 
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NZ^ME 

chdir - change working directory 



SWDPSIS 



int chdir (path) 
char *path; 



DESCRIPTION 



I&th points to the path name of a directory. Chdir causes the named 
directory to become the curroit working directory, the starting point for 
path searches for path names not beginning with /. 

Qidir will fail and the curroit working directory will be unchanged if 
one or more of the following are true: 

A component of the path name is not a directory. [ENOTDIR] 

The named directory does not exist. [ENOENT] 

Search permission is denied for aiv/ component of the path name. [EACCES] 

Bath points outside the process's allocated address space. [EFAULT] 



RETORN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value 
of -1 is returned and errno is set to indicate the error. 
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dmod 



The effective user ID does not match the cwner of the file. [EPERM] 
Bath points outside the process's allocated address space. [EFADLT] 

RETORN VALUE 

Upon successful ccmpletionf a value of is returned. Otherwise, a value 
of -1 is returned and errno is set to indicate the error. 
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NAME 

chnod - change mode of file 



SYNOPSIS 



int chnod (path, mode) 
char *path; 
int mode; 



DESCRIPTION 



Bath points to a path name ncining a file. Chmod sets the access 
permission portion of the named file's mode according to the bit pattern 
contained in mode. 

Access permission bits are interpreted as follows: 

00400 Read by owner 

00200 Write fcy owner 

00100 Execute (or search if a directory) by ovmer 

00070 Read, write, execute (search) by group 

00007 Read, write, execute (search) by others 

Chnnod will fail and the file mode will be unchanged if one or more of the 
following are true: 

A component of the path prefix is not a directory, [ENOIDIR] 
The named file does not exist. [ENOENT] 

Search permission is denied on .a component of the path prefix. 
[EACCES] 
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clearerr, f error, feof, f ileno - stream status inquiries 

SYNOPSIS 
See f error 
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close 



close - dose a file descriptor 



S"XNOPSIS 



int close (fildes) 
int fildes; 



DESCRIITION 



Fildes is a file descriptor obtained from a creat, open, or dup system 
call. Qose closes the file descriptor indicated fcy fildes. 

Close will fail if fildes is not a valid open file descriptor. [EBADF] 



RETORN VALUE 

Upon successful completion, a value of is returned. Otherwise, a value 
of -1 is returned and errno is set to indicate the error. 



SEE ALSO 



creat(2), di:?)(2), exec(2), opQi(2) , 
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NAME 

sin, cos, tan, asin, acos, atan, atan2 - trigonometric functions 

SYNOPSIS 
See trig 



cos~l 



cosh 



sinh, cosh, tanh - hyperbolic functions 

SYNOPSIS 
See sinh 
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creat 



The file c3oes not exist and the directory in which the file is to be 
created does not permit writing. [EACCES] 

The file is a pure procedure (shared text) file that is being 
executed. [ETXIBSY] 

The named file is an existing directory. [EISDIR] 

Twenty (20) file descriptors are currently open. [EMFILE] 

Path points outside the process's allocated address space. [EEMJLT] 

RETOEN VALUE 

Upon successful ccmpletionr a non-negative integer, namely the file 
descriptor, is returned. Otherwise, a value of -1 is returned and errno 
is set to indicate the error. 



SEE ALSO 

close(2), dup(2), lseek(2), open(2), read(2) , write ( 2) . 
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creat 



creat - create a n&t file or r&fiite an existing one 

SYNOPSIS 

int creat (path, mode) 
char *path; 
int mode; 



DESCRIITION 



Creat creates a new ordinary file or prepares to rewrite an existing file 
named ty the path name pointed to ty path. 

If the file exists, a n©/ version is created. 

Upon successful oompiletion, a nonmegative integer, namely the file 
descriptor, is returned. The file pointer is set to the beginning of the 
file. The file descriptor is set to remain open across exec syston 
calls. No process may have more than 20 files open simultaneously. A n&f 
file m^ be created with a mode that forbids writing. 

Creat will fail if one or more of the following are true: 

A component of the path prefix is not a directory. [ENCTDIR] 

A component of the path prefix does not exist. [ENOENT] 

Search permission is denied on a component of the path prefix. 
[EACCES] 

The path name is null. [ENOENT] 
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cryEt 

The argument to the oicrypt entry is a character array of loigth 64 
containing only the characters with numerical value and 1. The 
argument array is modified in place to a similar array representing the 
bits of the argument after having been subjected to the DES algorithm 
using the key set by setkey. If edflag is zero, the argument is 
encrypted; if non-zero, it is decrypted. 



BUGS 

The return value points to static data that are overwrittoi by each call. 
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crypt 



crypt, setkey, encrypt - generate DES encryption 



SYNOPSIS 



char *crypt (key, salt) 
char *key, *salt; 

char *k^; 

void encrypt (block, edflag) 
char *hlock; 
int edflag; 



DESCRIETION 



Crypt is the passt/ord encryption function. It is based on the IBS Data 
Encryption Standard (DES) , with variations intended (among other things) 
to frustrate use of hard/are implementations of the DES for key search. 

Key is a user's typed password. Salt is a two-character string chosen 
from the set [ar-zA-Z0-9 ./] ; this string is used to perturb the DES 
algorithm in one of 4096 diff ereit ways, after which the password is used 
as the key to encrypt tepeatedly a constant string. The returned value 
points to the encrypted password. The first two characters are the salt 
itself. 

The setkey and encrypt entries provide (rather primitive) access to the 
actual DES algorithm. The argument of setkey is a character array of 
length 64 containing only the characters with numerical value and 1. 
If this string is divided into groups of 8, the low-order bit in each 
group is ignored; this gives a 56-bit key which is set into the machine. 
This is the key that will be used with the above mentioned algorithn to 
encrypt or decrypt the string block with the function encrypt. 
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ctenaid 



SEE ALSO 



ttyname 
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ctermid 



ctermid - generate file name for terminal 



SYNOPSIS 



#include <stdio,h> 

char *ctermid(s) 
char *s; 



DESCRIPriOI 



Ctermid generates the path name of the controlling terminal for the 
current process, and stores it in a string. 

If s is a NULL pointer, the string is stored in an internal static area, 
the contents of which are overwritten at the next call to ctermid, and 
the address of which is returned. Otherwise, s is assumed to point to a 
character array of at least L_ctermid elements; the path name is placed 
in this array and the value of s is returned. The constant L_ctermid is 
defined in the <st_io,h> header file. 



NOTES 

The difference between ctermid and ttyname(3C) is that ttyname must be 

handed a file descriptor and returns the actual name of the terminal 
associated with that file descriptor, while ctermid returns a string that 

will refer to the terminal if used as a file name. Ihus ttyname is 

useful only if the process alreac^ has at least one file open to a 
terminal. 
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ctime 

constant width. 

Sun Sep 16 01:03:52 1973Vi\0 

Local time and gmtime return pointers to tm structures, described below. 
Local time corrects for the time zone and possible Daylight Savings Time; 
gmtime converts directly to Greenwich Mean Time (GMT) . 

Asctime converts a tm structure to a 26-character string, as shown in the 
above example, and returns a pointer to the string. 

Declarations of all the functions and externals, and the tm structure, 
are in the <time.h> header file. The structure declaration is: 

struct tm { 

int tm_sec; /* seconds (0-59) */ 

int tm_jnin; /* minutes (0-59) */ 

int tmjiour; /* hours (0-23) */ 

int tmjnday; /* day of month (1 - 31) */ 

int tmjnon; /* month of year (0-11) */ 

int tm_year; /* year - 1900 */ 

int tm_wday; /* day of week (Sunday = 0) */ 

int tm_yday; /* day of year (0 - 365) */ 

int tm_isdst; 
}; 

Tnuisdst is non-zero if Daylight Savings Time is in effect. 

The external long variable timezone contains the difference, in seconds, 
between GMT and local standard time (in EST, timezone is 5*60*60); the 
external variable daylight is nonr-zero if and only if the standard U.S.A. 
Daylight Savings Time conversion should be applied. The program knows 
about the peculiarities of this conversion in 1974 and 1975; if 
necessary, a table for these years can be extended. 

If the logical name TZ is defined, asctime uses it to override the 
default time zone. The value of TZ must be a three-letter time zone 
name, followed by a number representing the difference between local time 
and Greenwich Mean Time in hours, followed ty an optional three-letter 
name for a daylight time zone. For example, the setting for New Jersey 
would be ESTSEET. The effects of setting TZ are thus to change the 
values of the external variables timezone and daylight; in addition, the 
time zone names contained in the external variable 

char *tzname[2] = { "EST", "EOT" }; 

are set from the logical name TZ. The function tzset sets these external 
variables from TZ; tzset is called ty asctime and may also be called 
e:qplicitly by the user. 



ctime-2 



ctime 



mm 

ctime, local time, gmtime, asctime, tzset - convert date and time to 
string 



SYNOPSIS 

#include <time.h> 

char *ctime (clock) 
long *clock; 

struct tm *localtime (clock) 
long *clock; 

struct tm *gmtime (clock) 
long *clock; 

char *asctime (tm) 
struct tm *tni; 

extern long timezone; 

extern int daylight; 

extern char *tzname[2]; 

void tzset ( ) 



DESCRIPTION 

Ctime converts a long integer, pointed to by clock, representing the time 
in seconds since 00:00:00 GMT, January 1, 1970, and returns a pointer to 
a 26-character string in the following form. All the fields have 
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ctime 



SEE ALSO 
time 

BU3S 

The return values point to static c3ata whose content is overwritten by 
each call. 
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ctype 

isspace 

ispunct 
ispriru 

isgraph 
iscntrl 

isascii 



c is a space, tab, carriage returnr new-line, vertical tab, 
or form-feed, 

c is a punctuation character (neither control nor alphanumeric) 

c is a printing character, code 040 (space) through 0176 
(tilde) . 

c is a printing character, like isprint except false for space. 

c is a delete character (0177) or an ordinary control 
character (less than 040) • 

c is an ASQI character, code less than 0200. 



DIA3N0SriCS 



If the argument to any of these macros is not in the domain of the 
function, the result is undefined. 
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ctype 



mm 

isalpha, isupper, islcwer, isdigit, isxdigit, isalnum, isspace, ispunctf 
isprint, isgraph, iscntrl, isascii -classify characters 



SYNOPSIS 



#include <ctype,h> 

int isalpha (c) 
int c; 



• • • 



DESGRIETION 



These macros classify character-coded integer values ty table lookup. 
Each is a predicate returning nonzero for truer zero for false. Isascii 
is defined on all integer values; the rest are defined only where isascii 
is true and on the single non-ASCEI value EOF (-1 - see stdio(3S)) . 



isalpha 

isupper 

islcwer 

isdigit 

isxdigit 

isalnum 



c is a letter. 

c is an upper-case letter. 

c is a Icwer-case letter. 

c is a digit [0-9] . 

c is a hexadecijiial digit [0-9] , [A-F] or [a-f ] . 

c is an alphanumeric (letter or digit) . 
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cuserid 



cuserid - get character login name of the user 



SYNOPSIS 



tinclucte <stdio,h> 

char *cuserid (s) 
char *s; 



DESCKEPriON 



Cuserid generates a character-string representation of the login name of 
the cwner of the current process. If s is a NULL pointer, this 
representation is generated in an internal static area, the address of 
which is returned. Otherwise, s is assumed to point to an array of at 
least L_cuserid characters; the representation is left in this array. 
Ihe constant L_cuserid is defined in the <stdio.h> header file. 



DIA3N0STICS 



If the login name cannot be found, cuserid returns a NULL pointer; if s 
is not a NULL pointer, a null character (\0) will be placed at s[0] . 



SEE ALSO 
getlogin 
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Functions drand48 and erand48 return non-negative double- precision 
floating-point values uniformly distributed over the interval [0.0, "'1.0), 

Functions lrand48 and nrand48 return non-negative long integers uniformly 
distributed over the interval [0,2 sup31 ). 

Functions rarand48 and jrand48 return signed long integers uniformly 
distributed over the interval [-2 sup 31 ,2 sup 31 ) . 

Functions srand48r seed48 and loong48 are initialization entry points, 
one of which should be invoked before either drand48, lrand48 or mrand48 
is called, (Although it is not recommended practice, constant default 
initializer values will be supplied automatically if drand48, lrand48 or 
mrand48 is called without a prior call to an initialization entry point.) 
Functions erand48, nrand48 and jrand48 do not require an initialization 
entry point to be called first. 

All the routines work by generating a sequence of 48-bit integer values, 
X sub i , according to the linear congruential formula 

X sub{n+l}=(aX sub n+c) sub{roman modm}n>=0. 

The parameter ib=2 sup 48; hence 48-bit integer arithmetic is performed. 
Unless lcong48 has been invoked, the multiplier value a and the addend 
value c are given ty 

amark =roman 5DEECE66Dsub 16=roman 

273673163155sub 8 

clineup =roman Bsub 16=roman 13sub 8 . 

The value returned ty any of the functions drand48, erand48, lrand48, 
nrand48, mrand48 or jrand48 is computed by first generating the next 48- 
bit $X sub i$ in the sequence. Then the appropriate number of bits, 
according to the type of data item to be returned, are copied from the 
high-order (leftmost) bits of $X sub i$ and transformed into the returned 
value. 

The functions drand48, lrand48 and mrand48 store the last 48-bit X sub i 
generated in an internal buffer; that is why they must be initialized 
prior to being invoked. llie functions erand48, nrand48 and jrand48 
require the calling program to provide storage for the successive X sub i 
values in the array specified as an argument when the functions are 
invoked. That is wl:iy these routines do not have to be initialized; the 
calling program merely has to place the desired initial value of X sub i 
into the array and pass it as an argument. By using different arguments, 
functions erand48, nrand48 and jrand48 allow separate modules of a large 
program to generate several independent streams of pseudo-random numbers, 
i.e., the sequence of numbers in each stream will not depend upon how 
many times the routines have been called to generate numbers for the 
other streams. 
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drand48 



mm 

drand48, erand48, lrand48r nrand48, inrand48, jrand48r srand48, seed48f 
loong48 - generate uniformly distributed pseudo- random numbers 



SYNOPSIS 

double drand48 ( ) 

double erand48 (xsubi) 
unsigned short xsubi [3]; 

long lrand48 ( ) 

long nrand48 (xsubi) 
unsigned short xsubi [3]; 

long mrand48 ( ) 

long jrand48 (xsubi) 
unsigned short xsubi [3]; 

void srand48 (seedval) 
long seedval; 

unsigned short *seed48 (seedl6v) 
unsigned short seedl6v[3]; 

void lcong48 (param) 
unsigned short param[7]; 



DESC2aiTI0N 

This family of functions generates pseudo-random numbers using the well- 
known linear congruential algorithm and 48-bit integer arithmetic. 
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The initializer function srand48 sets the high-order 32 bits of X sub i 
to the 32 bits contained in its argument* The lew-order 16 bits of X sub 
i are set to the arbitrary value roman 33 0E sub 16 . 

Ihe initializer function seed48 sets the value of X sub i to the 48-bit 
value specified in the argument array. In addition, the previous value 
of X sub i is copied into a 48-bit internal buffer, used only fcy seed48, 
and a pointer to this buffer is the value returned by seed48. This 
returned pointer, which can just be ignored if not needed, is useful if a 
program is to be restarted from a given point at some future time - use 
the pointer to get at and store the last X sub i value, and then use this 
value to reinitialize via seed48 when the program is restarted. 

Ihe initialization function lcong48 allows the user to specify the 
initial X sub i , the multiplier value a, and the addend value c. 
Argument array elements param[0-2] specify X sub i , param[3-5] specify 
the multiplier a, and param[6] specifies the 16-bit addend c. After 
lcong48 has been called, a subsequent call to either srand48 or seed48 
will restore the standard multiplier and addend values, a and c, 
specified on the previous page. 



SEE ALSO 
rand 
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dup 



RETORN VALUE 



Upon successful ccmpLetion a non-negative integer, namely the file 
descriptor, is returned. Otherwise, a value of -1 is returned and ermo 
is set to indicate the error. 



SEE ALSO 



creat(2), close(2), exec(2), opQi(2) , 
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dup 



NZ^ME 

dup - duplicate an open file descriptor 



SYNOPSIS 



int dup (f ildes) 
int f ildes; 



DESCREITION 



Fildes is a file descriptor obtained from a creat, open, or dup, syston 
call, Dup returns a new file descriptor having the following in common 
with the original: 

Same open file. 

Same file pointer. (i.e., both file descriptors share one file 
pointer.) 

Same access mode (read, write or read/write). 

The new file descriptor is set to remain open across exec syston calls. 

The file descriptor returned is the lowest one available. 

Dup will fail if one or more of the following are true: 
Fildes is not a valid open file descriptor. [EBADF] 
IVenty (20) file descriptors are currently open. [EMFILE] 
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ecTt 

SEE ALSO 
printf 

BUSS 

The return values point to static data whose content is overwritten by 
each call. 
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ecvt 



mm 


ec7t, fcvt, gcvt - 


• convert floating-point number to string 


SYNOPSIS 



char *ec7t (value, ndigit, decpt, isign) 

double value; 

int ndigitf *decpt, *sign; 

char *fc7t (value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *gc7t (value, ndigit, buf ) 
double value; 
char *buf ; 



DESGRIPTIOJ 



Ecvt converts value to a null-terminated string of ndigit digits and 
returns a pointer thereto. The lew-order digit is rounded. The position 
of the decimal point relative to the beginning of the string is stored 
indirectly through decpt (negative means to the left of the returned 
digits) , The decimal point is not included in the returned string. If the 
sign of the result is negative, the word pointed to ty sign is non-zero, 
otherwise it is zero. Fcvt is identical to ecvt, except that the correct 
digit has been rounded for Fortran F-format output of the number of 
digits specified by ndigit. 

Gcvt converts the value to a null-terminated string in the array pointed 
to by buf and returns buf. It attonpts to produce ndigit significant 
digits in Fortran F-format if possible, otherwise E-format, rea(^ for 
printing. A minus sign, if there is one, or a decimal point will be 
included as part of the returned string. Trailing zeros are suppressed. 
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erf 



mm 

erf, erfc - error function and cxxnpLementary error function 

SYNOPSIS 

tindude <rrath,h> 

double erf (x) 
double x; 

double erfc (x) 
double x; 

DESCRIPTION 

Erf returns the error function of x, defined as {2 over sqrt 
pi} int from to x e sup {- t sup 2}'dt • 

Erfc, which returns 1,0 - erf(x), is provided because of the 
extreme loss, of relative accuracy if erf (x) is called for 
large x and the result subtracted from 1.0 (e.g. for x = 5, 
12 places are lost) . 

SEE ALSO 
exp 
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erfc 



mm 

erf, erfc - error function and ccmpLementary error function 

SYNOPSIS 
See erf 
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exec 



When a C program is executed, it is called as follows: 

main (argc, argv, envp) 

int argc; 

char **argv', **envp; 

where argc is the argument count and argv is an array of character 
pointers to the arguments themselves. As indicated, argc is 
conventionally at least one and the first menber of the array points to a 
string containing the name of the file. 

Path points to a path name that identifies the new process file. File 
points to the n&t process file. 

Arg0, argl, ..., arg_ are pointers to null- terminated character strings. 
These strings constitute the argument list available to the new process. 
By convention, at least arg0 must be present and point to a string that 
is the same as path (or its last component) . 

Argv is an array of character pointers to null-terminated strings. These 
strings constitute the argument list available to the new process. By 
convention, argv must have at least one member, and it must point to a 
string that is the same as path (or its last component) . Argv is 
terminated fcy a null pointer. 

Exec will fail and return to the calling process if one or more of the 
following are true: 

One or more components of the new process file's path name do not exist. 

[momr] 

A component of the new process file's path prefix is not a directory. 
[ENDTDIR] 

Search permission is denied for a directory listed in the new process 
file's path prefix. [EACCES] 

The new process file mode denies execution permission. [EACCES] 

The exec is not an execlp or execvp, and the new process file has the 
appropriate access permission but an invalid magic number in its header. 
[ENOEXEC] 

The new process file is a pure procedure (shared text) file that is 
currently open for writing fcy some process. [ETXIBSY] 

The new process requires more memory than is allowed by the syston- 
imposed maximum mXMEM. [ENOMBM] 
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exec 



mm 

exec, execl, execv, exede, execve, execlp, execvp - execute a file 

SY^DPSIS 

int execl (path, arg0, argl, •••, argn, 0) 
char *pathf *arg0/ *argl, .../ *argn; 

int execv (path, argv) 
char *pathr *argv[ ]; 

int execle (path, arg0r argl, .,., argn, d, envp) 
char *pathr *arg0f *argl, .•., *argnr *envp[ ]; 

int execve (path, argv, envp) 
char *pathf *argv[ ], *en7p[ ]; 

int execlp (file, arg0, argl, ..., argn, 0) 
char *file, *arg0, *argl, ..., *argn; 

int execvp (file, argv) 
char *file, *argv[ ]; 



DESCRIITia^ 

Exec creates a new process. The n&i process is constructed from an 
ordinary file called the new process file. Tliis file is an executable 
object file. An executable object file consists of a header a text 
segment, and a data segment. The data segment contains an initialized 
portion and an uninitialized portion (bss) . 
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exec 



The number of \jftes in the new process's argument list is greater than 
the system- impDsed limit of 5120 bytes. [E2BIG] 

The n&f process file is not as long as indicated ty the size values in 
its header. [EEMJLT] 

Path, argv, or envp point to an illegal address. [EFMJLT] 



RETOEN VALUE 

If exec returns an error, the return value will be -1 and errno will be 
set to indicate the error. 



SEE ALSO 
exit 
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exit 



exit, _exit - terminate process 



SYNOPSIS 



void exit (status) 
int status; 
void _exit (status) 
int status; 



DESCRIITION 



Exit terminates the calling process with the following consequences: 

All of the file descriptors open in the calling process are closed. 
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essp 

Pow returns x to the y power. The values of x and y may not both be 
zero. If X is non-positive, y must be an integer. 

Sqrt returns the square root of x. The value of x may not be negative. 



DIA3N0STICS 

Exp returns HUGE when the correct value would overflow, and sets errno to 
ERANSE. 

Log and logl0 return and set errno to EDOM when x is nonr-positive An 
error message is printed on the standard error output. 

Pow returns and sets errno to EDOM when x is nonr-positive and y is not 
an integer, or when x and y are both zero. In these cases a message 
indicating DOMAIN error is printed on the standard error output. When 
the correct value for pow would overflow, pow returns HUGE and sets errno 
to EPANGE. 

Sqrt returns and sets ermb to EDOM when x is negative. A message 
indicating DOMAIN error is printed on the standard error output. 



SEE ALSO 
hypot, sinh 
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exp 



NZ^ME 

exp, log, logl0, pow, sqrt - exponential, logarithm, pcwer, square root 
functions 



SYNOPSIS 



#include <math,h> 

double exp (x) 
double x; 

double log (x) 
double x; 

double logl0 (x) 
double x; 

double pow (x, y) 
double X, y; 

double sqrt (x) 
double x; 



DESCRIITiai 



Exp returns e to the x pcwer. 

Log returns the natural logarithm of x. The value of x must be positive. 

IiOgl0 returns the logarithm base ten of x. The value of x must be 
positive. 
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tabs 



mm 

tabs, floorf ceilf fmod, - floor, ceilingf remainder, absolute value 
functions 



SYNOPSIS 
See floor 
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fdose 

SEE ALSO 

closef exit, fopen, setbuf 
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fclose 



mm 

fdose, fflush - dose or flush a stream 



SYNOPSIS 



#include <stdio.h> 

int fclose (stream) 
FILE *stream; 

int fflush (stream) 
FILE *stream; 



DESCRIITION 



Fclose causes any buffered data for the named stream to be written out, 
and the stream to be closed. 

Fclose is performed autonatically for all open files upon calling 
exit (2). 

Fflush causes any buffered data for the named stream to be written to 
that file. The stream remains open. 



DIASNOSriCS 

These functions return for success, and EOF if any error (such as 
trying to write to a file that has not been opened for writing) was 
detected. 
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fdopen 



NZ^ME 

fdopen, freopen, fopen - open a stream 

SYNOPSIS 
See fopen 
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feof 



mME 


feof, f error, dearerr, f ileno - 


• stream status inquiries 


ST^NOPSIS 



See f error 
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ferror 



Fileno returns the integer file descriptor associated with the named 
stream; see open(2). 



NDTE 

All these functions are implemented as macros; they cannot be declared or 
redeclared. 



SEE ALSO 
open, fopen 
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terror 



MME 


f error, feof, clearerrf f ileno - 


Stream status inquiries 


SYNOPSIS 



tinclude <stdio.h> 

int feof (stream) 

FILE 

♦stream; 

int ferror (stream) 

FILE 

♦stream; 

void clear err (stream) 

FILE 

♦stream; 

int filQio (stream) 

FILE 

♦stream; 



DESCRIPTION 



Feof returns nonr-zero when EOF has previously been detected reading the 
named input stream, otherwise zero. 

Ferror returns non-zero whoi an I/O error has previously occurred reading 
frcm or writing to the named stream, otherwise zero. 

GLearerr resets the error indicator and EOF indicator to zero on the 
named stream. 
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fflush 



NZ^ME 

fflush, fdose, - dose or flush a stream 

SYNOPSIS 
See f close 
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fgetc 



NAME 

f getCr getchar, getc, getw - get character or word from stream 

SYNOPSIS 
See getc 
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fgets 



mm 

fgets, gets - get a string from a stream 

SWOVSIS 
See gets 
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fileno 



N2^ME 
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fileno, ferror, feoff clearerr, - stream status inquiries 

SYNOPSIS 
See f error 
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floor 



SEE ALSO 



abs 
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floor 



mm 

floor, ceil, fmod, fabs - floor, ceiling, remainder, absolute value 
functions 



SYNOPSIS 



#include <math.h> 

double floor (x) 
double x; 

double ceil (x) 
double x; 

double fmod (x, y) 
double X, y; 

double fabs (x) 
double x; 



DESCRIPTION 



Floor returns the largest integer (as a double-precision number) not 
greater than x. 

Ceil returns the smallest integer not less than x, 

Rnod returns x if y is zero, otherwise the number f with the same sign as 
X, such that x = iy + f for some integer i, and If I < |y|. 

Fabs returns |x| . 
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fmod 



mm 

fmodr ceilf floorf fabs - floor, ceilingr remainder, absolute value 
functions 



SYNOPSIS 
See floor 
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£open 



append; open for writing at oid of file, or 
create for writing 



n- I n 



r+" open for update (reading and writing) 

wf" truncate or create for update 

'a+" append; open or create for update at aid-of-file 



Freopen substitutes the named file in place of the opoi stream. The 
original stream is closed, regardless of whether the open ultimately 
succeeds. Freopen returns a pointer to the FILE structure associated 
with stream, 

Freopen is typically used to attach the preopened streams associated with 
stdin, stdout and stderr to other files, 

Pdopen associates a stream with a file descriptor obtained from open, 
dupf or creat, which will open files but not return pointers to a FILE 
structure stream which are necessary input for many of the section 3S 
library routines. The type of stream must agree with the mode of the open 
file. 

When a file is opened for update, both input and output may be done on 

the resulting stream, Hcwever, output may not be directly followed by 

input without an intervening fseek or rewind, and input may not be 

directly followed by output without an intervening fseek, rewind, or an 
input operation which encounters end-of-f ile. 

When a file is opened for append (i,e. , when type is "a" or "a+") , it is 
impossible to overwrite information alrea<^ in the file, Fseek may be 
used to reposition the file pointer to any position in the file, but when 
output is written to the file the current file pointer is disregarded. 
All output is written at the end of the file and causes the file pointer 
to be repositioned at the end of the output. If two separate processes 
open the same file for append, each process may write freely to the file 
without fear of destroying output being writtai by the other. The output 
from the two processes will be intermixed in the file in the order in 
which it is written. 



SEE ALSO 
open, fdose 

DIASNOSriCS 

Fopen and freopen return a NULL pointer on failure. 
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fopen 



fopen, f reopen, f dopen - open a stream 



SYNOPSIS 



tindude <stdio.h> 

FILE *fopen (file-name, type) 
char *file-name, *type; 

FILE *f reopen (file-name, type, stream) 
char *file-name, *type; 
FILE *stream; 

FILE *f dopen (fildes, type) 
int fildes; 
char *type; 



DESCRIPTION 



Fopen opois the file named by file-name and associates a stream with it. 
Fopen returns a pointer to the FILE structure associated with the stream. 

File-name points to a character string that contains the name of the file 
to be opened. 

Type is a character string having one of the following values: 

"r" open for reading 

"w" truncate or create for writing 



fopen-1 



fprintf 



fprintf, printf r sprintf - print fomatted output 

SYNOPSIS 
See printf 



fprintf-1 



fputc 



mm 

fputCr putchar, putc, putw - put character or word on a stream 

S^^NOPSIS 
See putc 
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fputs 



mm 

fputs f puts - put a string on a stream 

SYNOPSIS 
See puts 
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£read 



The variable size is typically sizeof(*ptr) where the pseudo-function 
sizeof specifies the loigth of an item pointed to ty ptr. If ptr points 
to a data type other than char it should be cast into a pD inter to char. 



SEE ALSO 
















read, write, 


fopen, 


getc, 


gets. 


printf. 


putc. 


puts. 


scanf 


Diiorasrics 



Fread and fwrite return the number of items read or written. If nitons is 
non-positive, no characters are read or written and is returned ty both 
fread and fwrite. 
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fread 



fread, fwrite - binary input/output 



SYNOPSIS 



♦include <stdio.h> 

int fread (ptr, size, nitems, stream) 

char *ptr; 

int size, nitems; 

FILE *stream; 

int fwrite (ptr, size, nitens, stream) 

char *ptr; 

int size, nitems; 

FILE *stream; 



DESCRIPTION 



Fread copies, into an array beginning at ptr, nitons items of data from 
the named input stream, where an item of data is a sequence of bytes (not 
necessarily terminated fcy a null byte) of length size. Fread stops 
appending bytes if an end-of-file or error condition is encountered while 
reading stream, or if nitems items have been read, Fread leaves the file 
pointer in stream, if defined, pointing to the byte following the last 
byte read if there is one, Fread does not change the contents of stream, 

BVrite appends at most nitems items of data f rem the the array pointed to 
by ptr to the named output stream, _write stops appending when it has 
appended nitons items of data or if an error condition is encountered on 
stream, EVrite does not change the contents of the array pointed to by 
ptr. 
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freopen 



mm 

freopen, fopen, fdopen - open a stream 

SYNOPSIS 
See f open 
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frexp 



mm 


frexp, lc3exp, modf 


- manipulate parts of floating-point numbers 


S^^NOPSIS 



double frexp (value, eptr) 
double value; 
int *eptr; 

double Idexp (value, exp) 
double value; 
int esq); 

double modf (value, iptr) 
double value, *iptr; 



DESCRIPriC^ 



Every non-zero number can be written uniquely as x* 2^n, where the 
mantissa (fraction) x is in the range 0.5 _ returns the mantissa of a 
double value, and stores the exponent indirectly in the location pointed 
to by eptr. 

Lde:^ returns the quantity value* 2 exp. 

Modf returns the signed fractional part of value and stores the integral 
part indirectly in the location pointed to fcy iptr. 



DIA3N0STICS 

If Idexp would cause overflow, HUGE is returned and errno is set to 
ERANSE. 
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fscanf 



fscanf f scanf , sscanf - convert fomatted input 

SYNOPSIS 
See scanf 



fscanf-1 



fseek 



Ftell returns the offset of the current byte relative to the beginning of 
the file associated with the named stream. 



SEE ALSO 



Iseek, fopen, ungetc 



DI^iGNOSriCS 



Fseek returns nonrzero for improper seeks, otherwise zero. An improper 
seek can be, for example, an fseek done on a file that has not been 
opened via fopen; in particular, fseek may not be used on a tenninal. 



WARNING 



Although on the UNIX System an offset returned by ftell is measured in 
bytes, and it is permissible to seek to positions relative to that 
offset, portability to non-UNIX Systems requires that an offset be used 
by fseek directly. Arithmetic may not meaningfully be performed on such a 
offset, which is not necessarily measured in tytes. 
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fseek 



fseek, rewind, ftell - reposition a file pointer in a stream 

SYNOPSIS 

#incluc3e <stdio.h> 

int fseek (stream, offset, ptrname) 
FILE *stream; 
long offset; 
int ptrname; 

void rewind (stream) 
FILE *stream; 

long ftell (stream) 
FILE *stream; 

DESCRIETION 

Fseek sets the position of the next input or output operation on the 
stream. The new position is at the signed distance offset tytes from the 
beginning, from the current position, or from the end of the file, 
according as ptrname has the value 0, 1, or 2. 

Rewind (stream) is equivalent to fseek (stream, 0L, 0), except that no 
value is returned. 

Fseek and ra/ind undo any effects of ungetc(3S) . 

After fseek or rewind, the next operation on a file opened for update may 
be either input or output. 
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ftell 



ftell, rewind, fseek - reposition a file pointer in a stream 

SYNOPSIS 
bee rseeK 
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fwrite 



mME 

fwrite, fread, - binary input/output 

SYNOPSIS 
See f read 
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If the correct value would overflew, gamma returns HUGE and sets ermo to 
ERAN3E. 



SEE ALSO 
exp 



gamma— 2 



gamma 



NZ^ME 

gamma - log gamma function 



SYNOPSIS 



tindude <math.h> 
extern int signgam; 

double gamma (x) 
double x; 



DESCKLFTim 



Gamnia returns In ( GAMMA (x) ), where GAMMA (x) is defined as int from to 
inf e sup { - t} t sup { x - 1 } dt. The sign of GAMMA (x) is returned in 
the external integer signgam. The argument x may not be a non-positive 
integer. 

The following C program fragment mi<^t be used to calculate GAMMA: 

if ((y = gamma (x)) > LOGHIEE) 

error ( ) ; 
y = signgam * exp(y) ; 

where LOGHUGE is the least value that causes e:^(3M) to return a range 
error. 



DMGNOSriCS 

For non-negative integer arguments HUGE is returned, and errno is set to 
EDOM. A message indicating DOMAIN error is printed on the standard error 
output. 

gamma— 1 



getc 

constant EDF upon end-of-file or error, but as that is a valid integer 
value, feof and ferror(3S) should be used to check the success of getw. 
Getw incronents the associated file pointer, if defined, to point to the 
next word. Getw assumes no special alignment in the file. 



SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), gets(3S), putc(3S) , 
scanf (3S) • 



DIPGW3JHCS 

These functions return the integer constant EOF at end-of-file or upon an 
error. 



BUSS 

Because it is implemented as a macro, getc treats incorrectly a stream 
argument with side effects. In particular, getc(*f-H-) doesn't work 
sensibly. Fgetc should be used instead. Because of possible differences 
in word length and byte ordering, files writtoi using putw are machine- 
dependent, and may not be read using getw on a different processor. 
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getc 



getc, getchar, f getc, getw - get character or word from stream 

SYNOPSIS 

#include <stdio,h> 

int getc (stream) 
FILE *stream; 

int getchar () 

int fgetc (stream) 
FILE *stream; 

int getw (stream) 
FILE *stream; 

DESCRIiTION 

II— —II. II 111 I i i . I II III— -I—I I II 111. -1. Ill I II I-. I 111 iiii . »i.i . . 

Getc returns the next character (i.e. byte) from the named input stream. 
It also moves the file pointer, if defined, ahead one character in 
stream. Getc is a macro and so cannot be used if a function is 
necessary; for example one cannot have a function pointer point to it. 

Getchar returns the next character from the standard input stream, stdin. 
As in the case of getc, getchar is a macro. 

Fgetc performs the same function as getc, but is a genuine function. 
Fgetc runs more slowly than getc, but takes less space per invocation. 

Getw returns the next word (i.e. integer) from the named input stream. 
The size of a word varies from machine to machine. It returns the 
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getchar 



mm 

getchar, getc, f getc, getw - get character or word from stream 

SYNOPSIS 
See getc 
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getcHd 



SEE ALSO 
malloc 

DIT^GNOSTICS 

Returns NULL with ermo set if s_?e is not large enough, or if an error 
ocurrs in a Icwer-level function. 
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getcwd 



mm 

getcwd - get pathrname of current working directory 

SYNOPSIS 

char *getcwd (buf, size) 
char *buf ; 
int size; 



DESCRIITIC^ 



Getcwd returns a pointer to the current directory path-name. The value of 
size must be at least two greater than the laigth of the path-name to be 
returned. 

If buf is a NULL pointer, getcwd will obtain size bytes of space using 
malloc(3C), In this case, the pointer returned by getcwd may be used as 
the argument in a subsequent call to free. 



EXAMPLE 



char *cwd, *getcwd(); 



if ((cwd = getcwd ((char *)NULL, 64)) = NULL) { 

perror("pwd"); 

exit(l); 

} 

printf ("%"sVir cwd); 
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getlogin 



MME 

getlogin - get login name 



S"XNOPSIS 



char *getlogin ( ); 



DESCRIPTION 



Getlogin returns a pointer to the login name. 

If getlogin is called within a process that is not attached to a 
terminal, it returns a NULL pointer. The correct procedure for 
determining the login name is to call cuserid. 



SEE ALSO 



cuserid 



DLAGNOSTICS 



Returns the NULL pointer if ,name not found. 



BUGS 



The return values point to static data whose content is overwritten by 
each call. s^ 
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Dli^GNOSriCS 

Getopt prints an error message on stderr and returns a question mark (?) 
when it encounters an option letter not included in optstring. 



WARNIMG 

The above routine uses <stdio.h>, which causes it to increase the size of 
programs/ not otherwise using standard 1/0, more than might be expected. 
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getopt 



getopt - get option letter f rem argument vector 



SYNOPSIS 



int getopt (argc, argv, optstring) 
int argc; 
char **argv; 
char *optstring; 

extern char *optarg; 
extern int optind; 



DESCRIPTION 



Getopt returns the next option letter in argv that matches a letter in 
optstring. Optstring is a string of recognized option letters; if a 
letter is followed fcy a colon, the option is expected to have an argument 
that may or may not be separated from it by white space, Optarg is set 
to point to the start of the option argument on return from getopt. 

Getopt places in optind the argv index of the next argument to be 
processed. Because optind is external, it is normally initialized to 
zero automatically before the first call to getopt. 

When all options have been processed (i.e., up to the first non-option 
argument) , getopt returns EOF. Ihe special option — may be used to 
delimit the end of the options; EOF will be returned, and — will be 
ski^^)ed. 
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getopt 



EXAMHiE 

•Hie following code fragment shews hew one might process the arguments for 
a command that can take the mutually exclusive options a and b, and the 
options f and o, both of which require arguments: 

main (argc, argv) 
int argc; 
char **argv; 

{ 

int c; i 

extern int optind; 
extern char *optarg; 



while ((c = getopt (argc, argv, "abf:o:")) 1= EOF) 
switch (c) { 



case 



,t . 



if (bflg) 

errflg4-t-; 

else 

aflg++; 

break; 
case 'b': 

if (aflg) 

errflg++; 

else 

bproc( ); 

break; 
case 'f: 

if ile = optarg; 

break; 
case *o': 

of ile = optarg; 

bufsiza = 512; 

break; 
case * ? * : 

errflg++; 

} 
if (errflg) { 

fprintf (stderr, "usage: . . • "); 
exit (2); 

} 

for ( ; optind < argc; optindH-) { 
if (access (argv [optind] , 4)) { 
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getpid 



mm 

getpid, getpgrp, getppid - get process, process group, and parent process 
IDs 



SYNOPSIS 



int getpid () 
int getpgrp () 
int getppid () 



DESCRIPriON 



Getpid returns the process ID of the calling process, 
Getpgrp returns the process group ID of the calling process. 
Getppid returns the parent process ID of the calling process, 

SEE ALSO 
exec 



getpid-1 



gets 



DliiGNOSriCS 



If end-of-file is encountered and no characters have been read, no 
characters are transferred to s and a NULL pointer is returned. If a 
read error occurs r such as trying to use these functions on a file that 
has not been opened for reading, a NULL pointer is returned. Otherwise s 
is returned. 
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gets 



N?y4E 

gets, f gets - get a string from a stream 



SYNOPSIS 



#include <stdio.h> 

char *gets (s) 
char *s; 

char *fgets (s, n, stream) 

char *s; 

int n; 

FILE *stream; 



DESCKEETIC^ 



Gets reads characters from the standard input stream, stdin, into the 
array pointed to ty s, until a new-line character is read or an end-of- 
file condition is aicountered. The new-line character is discarded and 
the string is terminated with a null character. 

Fgets reads characters from the stream into the array pointed to by s, 
until n-1 characters are read, or a new-line character is read and 
transferred to s, or an end-rof-f ile condition is encountered. The string 
is then terminated with a null character. 



SEE ALSO 



f error, fopen, fread, getc, scanf 
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getuid 



NZ^ME 


getuid, getgid. 


- set 


user 


and 


group 


IDs 


SYNOPSIS 



unsigned short getuid () 
unsigned short getgid () 



DESCRIPTION 



Getuid returns the user ID of the calling process. 
Getgid returns the group ID of the calling process, 
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getw 



getWr getchar, fgetc, getc - get character or word from stream 

SYNOPSIS 
See getc 
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>Maftarf^ 



entries that the table will contain. This number may be adjusted upward 
ty the algorithm in order to obtain certain mathematically favorable 
circumstances. 

Hdestroy destroys the search table, and may be followed fcy another call 
to hcreate. 



SEE ALSO 

bsearch ( 3C) , lsearch( 3C) , string ( 3C) , tsearch( 3C) . 



DIAGNOSTICS 

Hsearch returns a NULL pointer if either the action is FIND and the iten 
could not be found or the action is ENTER and the table is full. 

Hcreate returns zero if it cannot allocate sufficient space for the 
table. 



BU3S 

Only one hash search table may be active at any given time. 
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hsearch 



hsearchr hcreate, hdestroy - manage hash search tables 

SYNOPSIS 

#incluc3e <search,h> 

ENTEQf *hsearch (item, action) 
ENTRY item; 
ACTION action; 

int hcreate (nel) 
unsigned nel; 

void hdestroy ( ) 

DESCKEETiai 

Hsearch is a hash-table search routine generalized from Knuth (6,4) 
Algorithm D, It returns a pointer into a hash table indicating the 
location at which an entry can be found. Item is a structure of type 
ENTRY (defined in the <search.h> header file) containing two pointers: 
item, key points to the comparison key, and item, data points to any other 
data to be associated with that key. (Pointers to types other than 
character should be cast to pointer-to-character.) Action is a monber of 
an enumeration type ACTIC^ indicating the disposition of the oitry if it 
cannot be found in the table. ENTER indicates that the iton should be 
inserted in the table at an appropriate point. FIND indicates that no 
entry should be made. Unsuccessful resolution is indicated ty the return 
of a NULL pointer. 

Hcreate allocates sufficient space for the table, and must be called 
before hsearch is used. _el is an estimate of the maximum number of 
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hypot 



hypot - Euclidean distance function 



SYNOPSIS 



#include <math.h> 

double hypot (x, y) 
double X, y; 



DESOaPriON 



Hypot returns 

sqrt(x * X + y * y) , 
taking precautions against unwarranted overflows. 



DIiO«)SriCS 



When the correct value would overflow, hypot returns HUGE and sets ermo 
to ERANGE, 



SEE ALSO 
sqrt 
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jo 



mm 


j0. 


jlf JHf 


yt3f 


yir 


yn - 


- Bessel 


functions 


SYNOPSIS 



See bessel 
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j1 



jl, j0, jn, y0, ylf yn - Bessel functions 

SYNOPSIS 
See bessel 
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jn 



NAME 

jn, jl, j0, y0f ylf yn - BessaL functions 

SYNOPSIS 
See bessel 
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l3toi 



mm 

13tol, ltol3 - convert between 3-tyte integers and long integers 

SYNOPSIS 

void IStol dp, cpr n) 
long *lp; 
char *cp; 
int n; 

void ItolS (cpf Ipf n) 
char *cp; 
long *lp; 
int n; 

Description 

L3tol converts a list of n three-fcyte integers packed into a character 
string pointed to by cp into a list of long integers pointed to ty Ip. 

LtolS performs the reverse conversion from long integers (Ip) to three- 
byte integers (cp) . 

These functions are useful for file-system maintenance where the block 
numbers are three fcytes long. 



Bugs 

Because of possible differences in fcyte ordering, the numerical values of 
the long integers are machine-dependent. 
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164a 



NAME 

164a, a641 - convert between long integer and base-64 ASCII string 

SYNOPSIS 
See a641 
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log 



mm 

log, expr logl0, pow, sqrt - exponential, logarithm, pcwer, square root 
functions 



SYNOPSIS 
See exp 
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Iog10 



MME 

logl0, exp, log, pow, sqrt - exponential, logarithm, pcwer, square root 
functions 



SYNOPSIS 
See exp 
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1 search 



N3TES 



The pointers to the key and the element at the base of the table should 
be of type pointer-to-element, and cast to type po inter- to-charac±er. The 
comparison function need not compare every byte, so arbitrary data may be 
contained in the elements in addition to the values being compared. 
Although declared as type pointer-to-character, the value returned should 
be cast into type pointer-to-element. 



SEE ALSO 



bsearch(3C), hsearch(3C), tsearch(3C) . 



Diagnostics 



If the searched-for datum is found, both 1 search and Ifind return a 
pointer to it. Otherwise, Ifind returns NULL and Isearch returns a 
pointer to the newly added element. 



BU3S 



Undefined results can occur if there is not oiough room in the table to 
add a new item. 
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■search 



1 search - linear search and update 



SYNOPSIS 



#include <stdio.h> #include <search.h> 

char *lsearch ((char *)ke^, (char *)basef nelp, 
sizeof (*key), compar) 
unsigned *nelp; 
int (*compar) ( ) ; 

char *lfind ((char *)ker/, (char *)basef nelp, 

ccmpar) 

unsigned *nelp; int (*compar) ( ) ; 



DESCRIITION 



Lsearch is a linear search routine generalized from Knuth (6,1) Algorithm 
S, It returns a pointer into a table indicating where a datum may be 
found. If the datum does not occur, it is added at the end of the table. 
Key points to the datum to be sought in the table. Base points to the 
first element in the table. Nelp points to an integer containing the 
current number of elements in the table. The integer is increnoited if 
the datum is added to the table. Ccmpar is the name of the ccmparison 
function which the user must supply (stranpr for example) . It is called 
with to/o arguments that point to the elements being compared. The 
function must return zero if the elements are equal and non-zero 
otherwise. 
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JLORGK 



The resulting file pointer would be negative. [EINVAL] 

Some devices are incapable of seeking. The value of the file pointer 
associated with such a device is undefined. 



RETOEN VALUE 

Upon successful ccmpletion, a nonrnegative integer indicating the file 
pointer value is returned. Otherwise, a value of -1 is returned and 
ermo is set to indicate the error. 



SEE ALSO 



creat(2), dup(2), open(2) 
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Iseek 



MME 

Iseek - move read/write file pointer 



SYNOPSIS 



long Iseek (f ildes, offset, whence) 
int f ildes; 
long offset; 
int whence; 



DESCRIETICN 



Fildes is a file descriptor returned from a creat, open, or dup system 
call, Lseek sets the file pointer associated with fildes as follov/s: 

If whence is 0, the pointer is set to offset bytes. 

If whence is 1, the pointer is set to its curreit location plus 
offset. 

If whence is 2, the pointer is set to the size of the file plus 
offset. 

Upon successful completionr the resulting pointer location as measured in 
bytes from the beginning of ,the file is returned. 

Lseek will fail and the file pointer will renain unchanged if one or more 
of the following are true: 

Fildes is not an open file descriptor. [EBADF] 

Whence is not 0, 1 or 2. [EINVAL] 
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malloc 



coalescing adjacent free blocks as it searches. It calls sbrk (see 
brk(2)) to get more menory from the system when there is no suitable 
space already free, 

Realloc changes the size of the block pointed to by ptr to size bytes and 
returns a pointer to the (possibly moved) block. The contents will be 
unchanged up to the lesser of the new and old sizes. If no free block of 
size bytes is available in the storage arena, then realloc will ask 
malloc/'^ to enlarge the aroia fcy size bytes and will then move the data 
to the new space, 

Realloc also works if ptr points to a block freed since the last call of 
malloc, realloc, or calloc; thus sequences of free, malloc and realloc 
can e:q>loit the search strategy of malloc to do storage compaction. 

Calloc allocates space for an array of n_J.€ra elonents of size elsize. 
The space is initialized to zeros. 

Each of the allocation routines returns a pointer to space suitably 
aligned (after possible pointer coercion) for storage of any type of 
object. 



DIASNOSriCS 

Malloc, realloc and calloc return a NULL pointer if there is no available 
menory or if the arena has been detectatiy corrupted by storing outside 
the bounds of a block. When this happens the block pointed to fcy ptr m^^ 
be destroyed. 



NOTES 

Search time increases when many objects have been allocated; that is, if 
a program allocates but never frees, then each successive allocation 
takes longer. 
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malloc 



NAME 


malloc, freer realloc, calloc 


- main memory allocator 


SYNOPSIS 



char *malloc (size) 
unsigned size; 

void free (ptr) 
char *ptr; 

char *realloc (ptr, size) 
char *ptr; 
unsigned size; 

char *calloc (nelem, elsize) 
unsigned nelem, elsize; 



DESGRIITIQN 



Malloc and free provide a simpLe general-purpose memory allocation 
package. Malloc returns a pointer to a block of at least size bytes 
suitably aligned for any use. 

The argument to free is a- pointer to a block previously allocated fcy 
malloc; after free is performed this space is made available for further 
allocation, but its contents are left undisturbed. 

Undefined results will occur if the space assigned fcy malloc is overrun 
or if some random number is handed to free. 

Malloc allocates the first big enough contiguous reach of free space 
found in a circular search f rom^ the last block allocated or freed, 
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meflozy 

Memccpy copies characters from memory area s2 into si, stopping after the 
first occurrence of character c has been copied, or after n characters 
have been copied, whichever comes first. It returns a pointer to the 
character after the copy of c in si, or a NULL pointer if c was not found 
in the first n characters of s2. 

Memchr returns a pointer to the first occurrence of character c in the 
first n characters of memory area s, or a NULL pointer if c does not 
occur. 

Memcmp compares its arguments, looking at the first n characters only, 
and returns an integer less than, equal to,, or greater than 0, according 
as si is lexicograjMcally less than, equal to, or greater than s2. 

Memcpy copies n characters from memory area s2 to si. It returns si. 

Memset sets the first n characters in monory area s to the value of 
character c. It returns s . 



NOTE 

For user convenience, all these functions are declared in the optional 
<memory.h> header file. 



BUSS 

Mononp uses native character comparison, which is signed on MG68000S and 
HDP-lls, unsigned on other machines. 

Character movement is performed differently in different impl orientations. 
Thus overlapping moves may yield surprises. 
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monory/ memccpy, memchrr menanp, memcpy, monset - monory operations 

SYNOPSIS 

♦include <m€mory.h> 

char *m€mccpy (si, si, c, n) 
char *slr *s2; 
int c, n; 

char *m€nichr (s, c, n) 
char *s; 
int c, n; 

int memcrtip (si, s2, n) 
char *sl, *s2; 
int n; 

char *memcpy (si, s2, n) 
char *sl, *s2; 
int n; 

char *m€mset (s, c, n) 
char *s; 
int c, n; 



DESCRipriai 



These functions operate efficiently on memory areas (arrays of characters 
bounded by a count, not terminated ty a null character) . They do not 
check for the overflew of any receiving memory area. 
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MME 

mktonp - make a unique file name 



SYNOPSIS 



char *mktQnp (template) 
char *template; 



DESCRIHCK^ 



Mktemp replaces the contents of the string pointed to by tonplate by a 
unique file name, and returns the address of template. The string in 
template should look like a file name with six trailing Xs; mktonp will 
replace the Xs with a letter and the current process ID. The letter will 
be chosen so that the resulting name does not duplicate an existing file. 



SEE ALSO 



getpid(2), tmpfile(3S), tmpnam(3S) . 



BUGS 



It is possible to run out of letters. 
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0_EXCL If 0_EXCL and 0_CREAT are set, open will fail if the file 
exists. 

Upon successful completion a nonmegative integer, the file descriptor, 
is returned. 

The file pointer used to mark the current position within the file is set 
to the beginning of the file. 

The new file descriptor is set to remain open across exec syston calls. 

No process may have more than 20 file descriptors open simultaneously. 

The named file is opened unless one or more of the following are true: 

A component of the path prefix is not a directory. [ENDTDIR] 

0_CREAT is not set and the named file does not exist. [ENOENT] 

A component of the path prefix denies search permission. [EACCES] 

Oflag permission is denied for the named file. [EACCES] 

The named file is a directory and oflag is write or read/write. 
[EISDIR] 

Twenty (20) file descriptors are curroitly open. [EMFILE] 

Bath points outside the process's allocated address space. [EFAULT] 

0_CE^EAT and 0_EXCL are set, and the named file exists. [EEXIST] 

The system file table is full. [ENFILE] 

RETURN VALUE 

Upon successful completion, a nonr-negative integer, namely a file 
descriptor, is returned. Otherwise, a value of -1 is returned and ermo 
is set to indicate the error. 



SEE ALSO 



close, creat, dup, Iseek, read, write 
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NAME 

open - open for reading or writing 



SYNOPSIS 



#include <fcntl.h> 

int open (path, of lag [ , mode J ) 

char *path; 

int of lag, mode; 



DESCRIPTION 



I^th points to a path name naming a file. Open opens a file descriptor 
for the named file and sets the file status flags according to the value 
of ofLag. Qflag values are constructed fcy or-ing flags from the 
following list (only one of the first three flags belcw may be used) : 

OJRDONLY Open for reading only. 

OJfBCMjY Open for writing only. 

O^PEWR Open for reading and writing. 

O^NDELAY This flag may affect subsequent reads and writes. See read 
and write. 

0_J\PPEND If set, the file pointer will be set to the aid of the file 
prior to each write. 

0_CREftT If the file exists, a new version is created. 

OJTRJNC If the file exists, its length is truncated to and the 
mode and owner are unchanged. 
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point to are located in the text segment so that they can be shared in 
programs that are loaded pure. Ihis implies that they are read-only in 
pure programs and any attempts to change them will cause memory faults. 
However^ the sys^errlist array itself is in the data aegment and hence 
the pointers may be changed. 
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perror, errno, sys^errlist, sysjierr - system error messages 

SYNOPSIS 

void perror (s) 
char *s; 

extern int ermo; 

extern char *sys__errlist[] ; 

extern int sysjierr; 

DESCRIPTION 

Perror produces a message on the standard error output, describing the 
last error eioountered during a call to a syston or library function. The 
argument string s is printed first, then a colon and a blank, then the 
message and a new-line. To be of most use, the argument string should 
include the name of the program that incurred the error. The error number 
is taken from the external variable ermo, which is set when errors 
occur. It is not cleared when non-erroneous calls are made. 

To simplify variant formatting of messages, the array of message strings 
sys_errlist is provided, ermo can be used as an index in this table to 
get the message string without the new-line. sys_nerr is the largest 
message number provided for in the table. It should be checked because 
new error codes may be added to the system before they are added to the 
table. 

WARNING 

The text of the error messages that the pointers in the array sys__errlist 
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NAME 

powr exp, log, logl0, sqrt - exponential, logarithm, pcwer, square root 
functions 



SYNOPSIS 
See exp 
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Each conversion specification is introduced by the character %. After 
the %, the following appear in sequence: 

Zero or inore flags, which modify the meaning of the conversion 
specification. 

An optional decimal digit string specifying a minimum field width. 
If the converted value has fetter characters than the field width, it 
will be padded on the left (or right, if the left-adjustment flag 
(see below) has been givoi) to the field width; 

A precision that gives the minimum number of digits to appear for 
the d, o, u, X, or X conversions, the number of digits to appear 
after the decimal point for the e and f conversions, the maximum 
number of significant digits for the g conversion, or the maximum 
number of characters to be printed from a string in s conversion. 
The precision takes the form of a period (.) followed ty a decimal 
digit string: a null digit string is treated as zero. 

An optional 1 specifying that a following d, o, u, x, or X 
conversion character applies to a long integer arg. 

A character that indicates the type of conversion to be applied. 

A field width or precision may be indicated by an asterisk (*) instead of 
a digit string. In this case, an integer arg supplies the field width or 
precision. The arg that is actually converted is not fetched until the 
conversion letter is seen, so the args specifying field width or 
precision must appear before the arg (if any) to be converted. 

The flag characters and their meanings are: 

The result of the conversion will be left-justif ied within 
the field. 

+ The result of a signed conversion will always begin with a 
sign (+ or -) . 

blank If the first character of a signed conversion is not a 
sign, a blank will be prefixed to the result. This 
implies that if the blank and + flags both appear, the 
blank flag will be ignored. 

# This flag specifies that the value is to be converted to 
an alternate form. For c, d, s, and u conversions, the 
flag has no effect. For o conversion, it increases the 
precision to force the first digit of the result to be a 
zero. For x (X) conversion, a non^zero result will have 
0x (0X) prefixed to it. For e, E, f, g, and G 
conversions, the result will always contain a decimal 
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printf, fprintf , sprintf - print fonratted output 

SYNOPSIS 

♦include <stdio.h> 

int printf (format [ , arg ] ... ) 
char *fonnat; 

int f printf (stream, format [ , arg ] ... ) 
FILE *stream; 
char *format; 

int sprintf (s, format [ , arg ] ... ) 
char *s, fonnat; 



DESCRIPTION 

Printf places output on the standard output stream stdout. Fprintf places 
output on the named output stream. Sprintf places output, followed by 
the null character (\0) in consecutive bytes starting at *s; it is the 
user's responsibility to oisure that enough storage is available. Each 
function returns the number of characters transmitted (not including the 
\0 in the case of sprintf) , or a negative value if an output error was 
encountered. 

Each of these functions converts, formats, and prints its args under 
control of the format. The format is a character string that contains 
two types of objects: plain characters, which are siirply copied to the 
output stream, and conversion specifications, each of which results in 
fetching of zero or more args. The results are undefined if there are 
insufficient args for the format. If the format is e^diausted while args 
ronain, the excess args are simply ignored. 
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If the string pointer arg has the value zero, the result 
is undefined. A null arg will yield undefined results, 

% Print a %; no argument is converted. 

In no case does a non-existent or small field width cause truncation of a 
field; if the result- of a conversion is wider than the field width, the 
field is simply expanded to contain the conversion result. Qiaracters 
generated by printf and f printf are printed as if putc(3S) had been 
called. 



EXZ\MHiES 

To print a date and time in the form Sunday, July 3, 10:02, where weekday 
and month are pointers to null-terminated strings : 

printf ("%s, %s %d, %.2d:%.2d", weekday, month, day, hour, min) ; 

To print pi to 5 decimal places: 

printf ("pi = %.5f", 4*atan(1.0)); 

SEE ALSO 

ecvt, putc, scanf , stdio 
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pointr even if no digits follow the point (normally^ a 
decimal point appears in the result of these conversions 
only if a digit follows it) . For g and G conversions, 
trailing zeroes will not be removed from the result (which 
they normally are) . 

The conversion characters and their meanings are: 

d,o,u,XfX The integer arg is converted to signed decimal, unsigned 
octal, decimal, or hexadecimal notation (x and X) , 
respectively; the letters abcdef are used for x conversion 
and the letters ABCDEF for X conversion. The precision 
specifies the minimum number of digits to appear; if the 
value being converted can be represented in fewer digits, 
it will be expanded with leading zeroes. The default 
precision is 1. The result of converting a zero value 
with a precision of zero is a null string. 

f The float or double arg is converted to decimal notation 
in the style [-Jddd.ddd, where the number of digits after 
the decimal point is equal to the precision specification. 
If the precision is missing, 6 digits are output; if the 
precision is explicitly 0, no decimal point appears. 

e,E The float or double arg is converted in the style 
[-3d.ddde_dd, where there is one digit before the decimal 
point and the number of digits after it is equal to the 
precision; when the precision is missing, 6 digits are 
produced; if the precision is zero, no decimal point 
appears. The E format code will produce a number with E 
instead of e introducing the exponent. The exponent 
always contains at least two digits. 

g,G The float or double arg is printed in style f or e (or in 
style E in the case of a G format code) , with the 
precision specifying the number of significant digits. 
The style used depends on the value converted: style e 
will be used only if the exponent resulting from the 
conversion is less than -4 or greater than the precision. 
Trailing zeroes are removed from the result; a decimal 
point appears only if it is followed by a digit. 

c The character arg is printed. 

s The arg is taken to be a string (character pointer) and 
characters from the string are printed until a null 
character (\0) is encountered or the number of characters 
indicated ty the precision specification is reached. If 
the precision is missing, it is taken to be infinite, so 
all characters up to the first null character are printed. 
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of a word is the size of an integer and varies from machine to machine. 
Putw neither assumes nor causes special alignment in the file. 

Output streams, with the exception of the standard error stream stderr, 
are by default buffered if the output refers to a file and line-buffered 
if the output refers to a terminal. The standard error output stream 
stderr is fcy default unbuffered, but use of f reopen (see fopen(3S)) will 
cause it to become buffered or line-buffered. When an output stream is 
unbuffered infomation is queued for writing on the destination file or 
terminal as soon as written; when it is buffered many characters are 
saved up and written as a block; when it is line-buffered each line of 
output is queued for writing on the destination terminal as soon as the 
line is completed (that is, as soon as a new-line character is written or 
terminal input is requested). Setbuf may be used to change the stream's 
buffering strategy. 



SEE ALSO 

fclose(3S), ferror(3S), fopen(3S), fread(3S), printf(3S), puts(3S), 
setbuf (3S). 



DIASNOSriCS 

On success, these functions each return the value they have written. On 
failure, they return the constant EOF. This will occur if the file 
stream is not open for writing, or if the output file cannot be grown. 
Because EOF is a valid integer, ferror(3S) should be used to detect putw 
errors. 



BUSS 

Because it is implemented as a macro, putc treats incorrectly a stream 
argument with side effects. In particular, putc(c, *f ++) ; doesn't work 
sensibly. Fputc should be used instead. Because of possible differences 
in word lengt± and byte ordering, files written using putw are machine- 
dependent, and may not be read using getw on a different processor. For 
this reason the use of putw should be avoided. 
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mME 

putc, putchar, fputc, putw - put character or word on a stream 

SYNOPSIS 

#include <stdio.h> 

int putc (c, stream) 

char c; 

FILE *stream; 

int put char (c) 
char c; 

int fputc (c, stream) 

char c; 

FILE *stream; 

int putw (Wf stream) 

int w; 

FILE *stream; 

DESCRIETIOJ 

Putc writes the character c onto the output stream (at the position where 
the file pointer, if defined, is pointing) . Putchar(c) is defined as 
putc(c, stdout) . Putc and put char are macros, 

Fputc behaves like putc, but is a function rather than a macro. _putc 
runs more slowly than putc, but takes less space per invocation, 

Putw writes the word (i,e, integer) w to the output stream (at the 
position at which the file pointer, if defined, is pointing) . The size 
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putcharf putc, fputc, putw - put character or word on a stream 

SYNOPSIS 
See putc 
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SEE ALSO 

ferror, fopen, fread, printf , putc 



NOTES 



Puts appenc3s a new-line character while fputs does not. 
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puts, fputs - put a string on a stream 



SYNOPSIS 



#include <stdio.h> 

int puts (s) 
char *s; 

int fputs (Sr stream) 
char *s; 
FILE *stream; 



DESCRIPTION 



Puts writes the null-terminated string pointed to by s, followed by a 
new-line character, to the standard output stream stdout. 

Fputs writes the null-terminated string pointed to by s to the named 
output stream. 

Neither function writes the terminating null character. 



DIA3N0STICS 

Both routines return EOF on error. This will happen if the routines try 
to write on a file that has not beei opened for writing. 
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MME 

putw, putdiar, fputc, putc - put character or word on a stream 

SYNOPSIS 
See putc 
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SEE ALSO 

bsearch, Isearchr- string 
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MME 

qsort - quicker sort 



SYNOPSIS 



void qsort ((char *) base, nel, sizeof (*base), ccmpar) 
unsigned int nel; 
int (*ccmpar) ( ) ; 



DESCRIITiaJ 



Qsort is an implementation of the quicker-sort algorithm. It sorts a 
table of data in place. 

Base points to the elemoit at the base of the table, Nel is the number 
of elements in the table, Compar is the name of the comparison function, 
which is called with two arguments that point to the elements being 
compared. The function must return an integer less than, equal to, or 
greater than zero according as the first argumeit is to be considered 
less than, equal to, or greater than the second. 



NOTES 

The pointer to the base of the table should be of type pointer-to- 
element, and cast to type pointer- to-character. The comparison function 
need not compare every byte, so arbitrary data m^ be contained in the 
elements in addition to the values being compared. Although declared as 
type pointer-to-character, the value returned should be cast into type 
po int er-to-el ement . 
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randf srand - simple random-number generator 



SYNOPSIS 



int rand ( ) 

void srand (seed) 
unsigned seed; 



DESOUIHriaJ 



Rand uses a multiplicative oongruential random-number generator with 
period 2**32 that returns successive pseudo-random numbers in the range 
from to 2**15. 

Srand can be called at any time to reset the random-number generator to a 
random starting point, Tlie generator is initially seeded with a value of 
1. 



NOTES 

•Hie spectral properties of rand leave a great deal to be desired. 
Drand48(3C) provides a much better, though more elaborate, random-number 
generator. 



SEE ALSO 
drand48(3C). 
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NAME 


rewind, fseek, ftell - 


■ reposition a file pointer in a stream 


SYNOPSIS 



See f seek 
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The cxjntrol string may contain: 

1. White-space characters (blanks, tabs, new-lines, or form-feeds) 
which, except in two cases described below, cause input to be 
read up to the next non-white-space character. 

2. An ordinary character (not %) , which must match the next 
character of the input stream. 

3. Conversion specifications, consisting of the character %, an 
optional assignment suppressing character *, an optional 
numerical maximum field width, an optional 1 or h indicating the 
size of the receiving variable, and a conversion code. 

A conversion specification directs the conversion of the next input 
field; the result is placed in the variable pointed to by the 
corresponding argument, unless assignment suppression was indicated by *. 
The suppression of assignment provides a way of describing an input field 
which is to be skipped. An input field is defined as a string of non- 
space characters; it extoids to the next inappropriate character or until 
the field width, if specified, is exhausted. 

The conversion code indicates the interpretation of the input field; the 
corresponding pointer argumoit must usually be of a restricted type. For 
a suppressed field, no pointer argument should be given. The following 
conversion codes are accepted: 

% a single % is e^q^ected in the input at this point; no 
assignment is done. 

d a decimal integer is expected; the corresponding argument 
should be an integer pointer. 

u an unsigned decimal integer is expected; the corresponding 
argument should be an unsigned integer pointer. 

o an octal integer is e^qpected; the corresponding argument should 
be an integer pointer. 

X a hexadecimal integer is e:q)ected; the corresponding argument 
should be an integer pointer. 

e,f,g 

a floating point number is expected; the next field is 
converted accordingly and stored through the corresponding 
argument, which should be a pointer to a float. The input 
format for floating point numbers is an optionally signed 
string of digits, possibly containing a decimal point, followed 
by an optional exponent field consisting of an E or an e, 
foU^wed by an optionally signed integer. 
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NZVME 

scanf , fscanf , sscanf - convert fonnatted input 



SYWPSIS 



#include <stdio.h> 

int scanf (format [ , pointer ] ... ) 
char *fonnat; 

int f scanf (stream, format [ , pointer ] ... ) 
FILE *stream; 
char *format; 

int sscanf (s, format [ , pointer ] ... ) 
char *s, *format; 



DESCRIHTION 



Scanf reads from the standard input stream stdin. Fscanf reads from the 
named input stream. Sscanf reads fran the character string s. Each 
function reads characterSf interprets then according to a format, and 
stores the results in its arguments. Each e^^^cts, as arguments, a 
control string format described below, and a set of pointer arguments 
indicating where the converted input should be stored. 

The control string usually contains conversion specifications, which are 
used to direct interpretation of input sequences. 



scanf-1 



scanf 



an input character and the control string. If the input aids before the 
first conflict or conversion, EOF is returned. 



EXAMHiES 



The call: 

int i; float x; char name [50]; 
scanf ("%d%f%s", &i, Sx, name); 

with the input line: 

25 54.32E-1 thonpson 

will assign to i the value 25, to x the value 5.432, and name will 
contain thompson\0. Or: 

int i; float x; char name [50]; 

scanf ("%2d%f%*d %[0-9]", &i, &x, name); 

with input: 

56789 0123 56a72 

will assign 56 to i, 789.0 to x, skip 0123, and place the string 56\0 in 
name. The next call to getchar (see getc(3S)) will return a. 



SEE ALSO 



atof, getc, printf, strtol 



NOTES 

Trailing white space (including a new-line) is left unread unless matched 
in the control string. 



DIASNOSriCS 

These functions return EOF on end of input and a short count for missing 
or illegal data items. 
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s a character string is expected; the corresponding argument 
should be a character pointer pointing to an array of 
characters large enough to accept the string and a terminating 
\0r v^ch will be added automatically. The input field is 
terminated by a white-space character, 

c a character is e^^jected; the corresponding argument should be a 
character pointer. The normal skip over white space is 
suppressed in this case; to read the next non-space character , 
use %ls. If a field width is given, the corresponding argument 
should refer to a character array; the indicated number of 
characters is read. 

[ indicates string data and the normal skip over leading white 
space is suppressed. The left bracket is followed ty a set of 
characters, which we will call the scanset, and a right 
bracket; the input field is the maximal sequence of input 
characters consisting entirely of characters in the scanset. 
The circumflex, O, when it appears as the first character in 
the scanset, serves as a complement operator and redefines the 
scanset as the set of all characters not contained in the 
ranainder of the scanset string. There are some conveitions 
used in the construction of the scanset. A range of characters 
may be represented by the construct first-last, thus 
[0123456789] m^ be expressed [0-9] . 

Using this convention, first must be lexically less than or 
equal to last, or else the dash will stand for itself. The 
dash will also stand for itself whenever it is the first or the 
last character in the scanset. To include the right square 
bracket as an el orient of the scanset, it must appear as the 
first character (possibly preceded fcy a circumflex) of the 
scanset, and in this case it will not be syntactically 
interpreted as the closing bracket. The corresponding argument 
must point to a character array large enough to hold the data 
field and the terminating \0, which will be added 
automatically. 

Ihe conversion characters d, u, o, and x may be preceded by 1 or h to 
indicate that a pointer to long or to short rather than to int is in the 
argument list. Similarly, the conversion characters e , f , and g may be 
preceded fcy 1 to indicate that a pointer to double rather than to float 
is in the argument list. 

Scanf conversion terminates at EOF, at the end of the control string, or 
when an input character conflicts with the control string. In the latter 
case, the offending character is left unread in the input stream. 

Scanf returns the number of successfully matched and assigned input 
items; this number can be zero in the event of an early conflict between 
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BUSS 

The success of literal itatches and suppressed assignments is not directly 
determinable. 
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sethnf 

SEE ALSO 

fopen, getc, malloc, putc 



NOTES 



A cxxnmon source of error is allocating buffer space as an automatic 
variable in a code block, and then failing to close the stream in the 
same block. 
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setbuf - assign buffering to a stream 



SYNOPSIS 



#include <stdio.h> 

void setbuf (stream, buf ) 
FILE *stream; 
char *buf ; 



DESCRIITION 



Setbuf is used after a stream has been opened but before it is read or 
written. It causes the character array pointed to ty buf to be used 
instead of an automatically allocated buffer. If buf is a NULL character 
pointer input/output will be completely unbuffered. 

A constant BUFSIZ, defined in the <stdio.h> header file, tells how big an 
array is needed: 

char buf[BUFSIZ]; 

A buffer is normally obtained from malloc(3C) at the time of the first 
getc or putc(3S) on the file, except that the standard error stream 
stderr is normally not buffered. 

Output streams directed to terminals are always line-buffered unless they 
are unbuffered. 
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WARNING 



If longjmp is called when env was never primed by a call to setjmp, or 
when the last such call is in a function which has since returned, 
absolute chaos is guaranteed. 
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NZ^ME 

setjmp, longjmp - non-local goto 



SYNOPSIS 



#include <setjrap.h> 

int setjmp (env) 
jmp_jDuf env; 

void longjmp (env, val) 
jmpjDuf env; 
int val; 



DESCRIPria^ 



These functions are useful for dealing with errors and interrupts 
encountered in a lew-level subroutine of a program. 

Setjmp saves its stack environment in env (whose type, jmpjDuf, is 
defined in the <setjmp.h> header file) , for later use by longjmp. It 
returns the value 0. 

Longjmp restores the environment saved by the last call of setjmp with 
the corresponding env argument. After longjmp is completed program 
execution continues as if the corresponding call of setjnp (which must 
not itself have returned in the interim) had just returned the value val. 
Longjmp cannot cause setjirp to return the value 0. If longjmp is invoked 
with a second argument of 0, setjmp will return 1. All accessible data 
have values as of the time longjmp was called. 



setjmp-1 



setvbuf 



setbuf - assign buffering to a stream 

SYNOPSIS 
See setbuf 
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mm 


sin, cos, tan, asin, acx>s, atan, atan2 - 


- trigonometric functions 


SYNOPSIS 



See trig 
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NZ^ME 


sinhr 


cx)sh, 


tanh - 


hyperbolic 


functions 


SYNOPSIS 



#include <math.h> 

double sinh (x) 
double x; 

double cosh (x) 
double x; 

double tanh (x) 
double x; 



DESGREETiai 



Sinhr cosh and tanh return respectively the hyberbolic sine, cosine and 
tangent of their argumoit. 



DIASNOSriCS 



Sinh and cosh return HUGE when the correct value would overflow, and set 
errno to ERAN3E. 
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NAME 

sleep - suspend execution for interval 



SYNOPSIS 



unsigned sleep (seconds) 
unsigned seconds; 



DESCRIPTICN 



The current process is suspended from execution for the number of seconds 
specified by the argument. The actual suspension time m^ be less than 
that requested. Also, the suspension time may be longer than requested ty 
an arbitrary amount due to the scheduling of other activity in the 
system. The value returned by sleep will be the unslept amount (the 
requested time minus the time actually slept) in case the caller had an 
alarm set to go off earlier than the end of the requested sleep time, or 
premature arousal. 

The routine is implenented ty setting an alarm and pausing until it 
occurs. The previous state of the alarm is saved and restored. The 
calling program may have set up an alarm before calling sleep; if the 
sleep time exceeds the time till such alarm, the process sleeps only 
until the alarm would have occur red, and the caller's alarm catch routine 
is executed just before the sleep routine returns, but if the sleep time 
is less than the time till such alann, the prior alarm time is reset to 
go off at the same time it would have without the intervening sleep. 
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sprintf 



mm 

sprintf r fprintf f printf - print formatted output 

SYNOPSIS 
See printf 
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sqrt 



sqrt, exp, log, logl0, pow, - exponential, logarithm, pcwer, square root 
functions 



SYNOPSIS 
See exp 
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sscanf 



mm 

sscanf, fscanf , - convert formatted input 

SYNOPSIS 
See scanf 
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Stat 



The contents of the structure pointed to by buf include the following 
members: 

ushort st_jnode; /* File mode */ 

ino_t st_ino; /* FCB number */ 

dev_t st^dev; /* Not used */ 

deyj: st_j:de7; /* Not used */ 

short' st_jilink; /* Number of links (always 1) */ 

ushort st__uid; /* User ID of the file's ovmer */ 

ushort st_gid; /* Group ID of the file's group */ 

off_t st_3ize; /* File size in bytes */ 

time_t st_atime; /* Not used */ 

timej: stjmtime; /* Time of last data modification 

V 

time_t st_ctime; /* Time file was created */ 

/* Times measured in seconds since */ 
/* 00:00:00 G^^', Jan. 1, 1970 */ 

stjntime Time when data was last modified. Qianged by the 
following systen calls: creat, and write. 

st__ctime Time when the file was created. Changed by the following 
system calls: creat, 

Stat will fail if one or more of the following are true: 

A component of the path prefix is not a directory. [ENOIDIR] 

The named file does not exist. [ENOENT] 

Search permission is denied for a component of the path prefix. 
[EACCES] 

Buf or path points to an invalid address. [EFMJLT] 

Fstat will fail if one or more of the following are true: 

Fildes is not a valid open file descriptor. [EBADF] 

Buf points to an invalid address. [EFAULT] 



RETURN VALUE 

Upon successful completion a value of is returned. -Otherwise, a value 
of -1 is returned and ermo is set to indicate the error. 
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Stat 



NZ^ME 


statf 


f Stat - 


- get 


file 


status 


SYNOPSIS 



#include <sys/types.h> 
#incluc3e <sys/stat.h> 

int Stat (path, buf ) 
char *path; 
struct Stat *buf ; 

int fstat (fildes, buf) 
int f ildes; 
struct Stat *buf ; 



DESCRIETION 



I^th points to a path name naning a file. Read, write or execute 
permission of the named file is not required, but all directories listed 
in the path name leading to the file must be searchable. Stat obtains 
information about the named file. 

Similarly, fstat obtains information about an open file known by the file 
descriptor f ildes, obtained from a successful open, creat, dup, fcntl, or 
pipe system call. 

Buf is a pointer to a stat structure into which information is placed 
concerning the file. 
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Stat 



SEE ALSO 

dmodr creat, read, time, unlink, write 
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string 



strcatf stmcatr strc3npr stmanpr strcpyr stmcpy, strlen, strchr, 
strrchr, strpbrk, strspn, strcspi, strtok - string operations 



SYNOPSIS 
See string 
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swab 



swab - ^/ap tytes 



SYNOPSIS 



void swab (fronir to, ntytes) 
char *fromf *to; 
int nfcytes; 



DESGRIETION 



Swab cx>pies nfcytes tytes pointed to by from to the array pointed to by 
to, exchanging adjacent even and odd tytes. It is useful for carrying 
binary data between PDP-lls and other machines, Ntytes should be even 
and nonrnegative. If ntytes is odd and positive swab uses ntytes-1 
instead. If ntytes is negative swab does nothing. 
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s^stc 



DIASNOSTICS 



^stem exec's the cip in order to execute string. If the exec fails, 
system returns -1 and sets ermo. 
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system 



NAME 

system - issue a cip canmand 



SYNOPSIS 



#include <stdio.h> 

int system (string) 
char *string; 



DESCRIETION 



l^stem causes the string to be given to the cip as inputr as if the 
string had been typed as a command at a terminal. The curroit process 
waits until the cip has completed, then returns the exit status of the 
cip. 



FILES 



sys $disk/sy sexe/cip. exe 



SEE ALSO 
exec 
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tan 



mm 


tan, sin, cos, asin/ aooSf atan, atan2 - 


trigonometric functions 


SYNOPSIS 



See trig 
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tanh 



mm 

tanhr sinh, c»sh, - hyperbolic functions 

SYNOPSIS 
See sinh 
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tempnam 



NZ^ME 

tempnanir tempnam - create a name for a temporary file 

SYNOPSIS 
See tmpnam 



tonpiam— 1 



time 



mm 

time - get time 

SYNOPSIS 

long time ((long *) 0) 

long time (tloc) 
long *tloc; 



DESCKEETiai 



Time returns the value of time in seconds since 00:00:00 GMT, January 1, 
1970. 

If tloc (taken as an integer) is non-zero, the return value is also 
stored in the location to which tloc points. 

Time will fail if tloc points to an illegal address. [EFAULT] 



REraRN VALUE 

Upon successful completion, time returns the value of time. Otherwise, a 
value of -1 is returned and ermo is set to indicate the error. 
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tmpfile 



tmpfile - create a temporary file 



SYNOPSIS 



#include <stdio.h> 
FILE *tinpfile 



DESCRIPriOI 



•Dnpfile creates a temporary file and returns a corresponding FILE 
pointer. The file will automatically be deleted when the process using 
it terminates. The file is opened for update. 



SEE ALSO 



creat, unlink, fopen, mktemp, tmpnam 
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Qwironment, whose value is a path-name for the desired temporary-file 
directory, 

Mariy applications prefer their temporary files to have certain favorite 
initial letter sequences in their names. Use the pfx argument for this. 
This argument may be NULL or point to a string of up to five characters 
to be used as the first fa/ characters of the temporary-file name. 

Tempnam uses malloc(3C) to get space for the constructed file name, and 
returns a pointer to this area. Thus, any pointer value returned from 
tempnam may serve as an argument to free (see malloc(3C)). If tonpnam 
cannot return the expected result for any reason, i.e. malloc failed, or 
none of the above mentioned attempts to find an appropriate directory was 
successful, a NULL pointer will be returned. 



^DTES 

These functions generate a different file name each time they are called. 

Files created using these functions and either fopen or creat are 
tonporary only in the sense that they reside in a directory intended for 
temporary use, and their names are unique. It is the user's 
responsibility to use unlink (2) to remove the file when its use is ended. 



SUK ALi^ 


creat. 


unlink. 


fopen. 


malloc. 


mktemp. 


tmpfiLe 


BUGS 



If called more than 17,576 times in a single process, these functions 
will start recycling previously used names. Between the time a file name 
is created and the file is opened, it is possible for some other process 
to create a file with the same name. This can never happen if that other 
process is using these functions or mktemp, and the file names are chosen 
so as to render duplication by other means unlikely. 
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tmpnam 



mm 


tuipnanif tempnain ~* 


create 


a 


name 


for 


a 


temporary 


file 


SYNOPSIS 



#include <stdio.h> 

char *tmpiam (s) 
char *s; 

char *tempnam (dir, pfx) 
char *dir, *pfx; 



DESCRIPTION 



These functions generate file names that can safely be used for a 
tonporary file, 

Ihipiam alw^s generates a file name using the path-name defined as 
P_tmpdir in the <stdio.h> header file. If s is NULL, tmpnam leaves its 
result in an internal static area and returns a pointer to that area. 
The next call to tmpnam will destroy the contents of the area. If s is 
not NULL, it is assumed to be the address of an array of at least 
L_tmpnam bytes, where L_tmpnam is a constant defined in <stdio.h>; tmpnam 
places its result in that array and returns s. 

Tempnam allows the user to control the choice of a directory. The 
argument dir points to the path-name of the directory in which the file 
is to be created. If dir is NULL or points to a string which is not a 
path-name for an appropriate directory, the path-name defined as P__tmpdir 
in the <stdio.h> header file is used. If that path-name is not 
accessible, /tmp will be used as a last resort. This entire sequence can 
be up-staged by providing a logical name TMPDIR in the user's 
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trig 

Asin returns the arcsine of x, in the range -pi/2 to pi/2. 

Acos returns the ar coo sine of x, in the range to pi. 

Atan returns the arctangent of x, in the range -pi/2 to pi/2. 

Atan2 returns the arctangent of y/x, in the range -pi to pi, using the 
signs of both arguments to determine the quadrant of the return value. 

DIAGNOSTICS 

Sin, cos and tan lose accuracy when their argument is far from zero. For 
arguments sufficiently large, these functions return when there would 
otherwise be a complete loss of significance. In this case a message 
indicating TLOSS error is printed on the standard error output. For less 
extreme arguments, a PLOSS error is generated but no message is printed. 
In both cases, ermo is set to ERANGE. 

Tan returns HUGE for an argument which is near an odd multiple of pi/2 
when the correct value would overflow, and sets ermo to ERANSE. 

Arguments of magnitude greater than 1.0 cause asin and acos to return 
and to set ermo to EDOM. In addition, a message indicating DOMAIN error 
is printed on the standard error output. 



trig-2 



trig 



mm 

trig, sirir oosr tan, asin, aoosr atan, atan2 - trigonometric functions 

SYNOPSIS 

#include <iiath.h> 

double sin (x) 
double x; 

double cos (x) 
double x; 

double tan (x) 
double x; 

double asin (x) 
double x; 

double acos (x) 
double x; 

double atan (x) 
double x; 

double atan2 (y, x) 
double X, y; 

DESCRIPTION 

Sin, COS and tan return respectively the sine, cosine and tangent of 
their argument, which is in radians. 
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tsearcfa 

The variable pointed to ty rootp will be changed if the deleted node was 
the root of the tree. Tdelete returns a pointer to the parent of the 
deleted node, or a NULL pointer if the node is not found. 

TValk traverses a binary search tree. Root is the root of the tree to be 
traversed. (Any node in a tree may be used as the root for a walk below 
that node.) Action is the name of a routine to be invoked at each node. 
This routine is, in turn, called with three arguments. The first 
argument is the address of the node being visited. The second argument 
is a value from an enumeration data type typedef enum { preorder, 
postorder, endorder, leaf } VISIT; (defined in the <search.h> header 
file) , depending on whether this is the first, second or third time that 
the node has been visited (during a depth-first, left-to- right traversal 
of the tree) , or whether the node is a leaf. The third argument is the 
level of the node in the tree, with the root being level zero. 



NOTES 



The pointers to the key and the root of the tree should be of type 
pointer-to-element, and cast to type pointer-to-character. The comparison 
function need not compare every tyte, so arbitrary data may be contained 
in the elements in addition to the values being compared. Although 
declared as type pointer-to-character, the value returned should be cast 
into type pointer-to^element. 

WARNINS: The root argument to twalk is one level of indirection less 
than the rootp arguments to tsearch and tdelete. 



DIAGNOSTICS 

A NULL pointer is returned ty tsearch if there is not enough space 
available to create a new node. A NULL pointer is returned ty tsearch and 
tdelete if rootp is NULL on entry. 



SEE ALSO 



bsearch ( 3C) , hsear ch ( 3C) , Isear ch ( 3C) . 



BUGS 

Pi/ffuL things can happen if the calling function alters the pointer to the 
root. 
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tsearch 



N2VME 

tsearchr tdelete, twalk - manage binary search trees 

SYNOPSIS 

#include <search.h> . 

char *t search ((char *) key, (char **) rootp, compar) 
int (*caiipar) ( ); 

char *tdelete ((char *) key, (char **) rootp, oompar) 
int (*compar) ( ); 

void twalk ( (char *) root, action) 
void (*action) ( ); 



DESCRIPTION 

Tsearch is a binary tree search routine generalized from Knuth (6.2.2) 
Algorithm T. It returns a pointer into a tree indicating where a datum 
may be found. If the datum does not occur, it is added at an appropriate 
point in the tree. Key points to the datum to be sought in the tree. 
Rootp points to a variable that points to the root of the tree. A NULL 
pointer value for the variable denotes an empty tree; in this case, the 
variable will be set to point to the datum at the root of the n&f tree. 
Compar is the name of the comparison function. It is called with two 
arguments that point to the elements being compared. The function must 
return an integer less than, equal to, or greater than zero according as 
the first argument is to be considered less than, equal to, or greater 
than the second. 

Tdelete deletes a node from a binary search tree. It is generalized from 
Knuth (6.2.2) algorithn D. The arguments are the same as for tsearch. 
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BUGS 

"Hie return value points to static data whose content is overwritten by 
each call. 
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ttyname 



mm 

ttyname, isatty - find name of a terminal 



SYNOPSIS 



char *ttyname (fildes) 
int fildes; 

int isatty (fildes) 
int fildes; 



DESGRIPriOJ 



Ttyname returns a pointer to a string containing the null-terminated path 
name of the terminal device associated with file descriptor fildes. 

Isatty returns 1 if fildes is associated with a terminal device, 
otherwise. 



FILES 



/dev/^ 



DliOJOSTICS 



Ttyname returns a NULL pointer if fildes does not describe a terminal 
device. 
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ungetc 



DIASNOSriCS 



In order that ungetc perform correctly, a read statement must have been 
performed prior to the call of the ungetc function, Ungetc returns EOF 
if it can't insert the character. In the case that stream is stdin, 
ungetc will allow exactly one character to be pushed back onto the buffer 
without a previous read statement. 
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ungetc 



mm 

ungetc ~ push character back into input stream 



SYNOPSIS 



#include <stdio.h> 

int ungetc (c, stream) 
char c; 
FILE *stream; 



DESC3a:iTIC^ 



Ungetc inserts the character c into the buffer associated with an input 
stream. Ihat character, c, will be returned by the next getc call on 
that stream, Ungetc returns c, and leaves the file stream unchanged. 

One character of pushback is guaranteed provided something has been read 
from the stream and the stream is actually buffered. 

If c equals EOF, ungetc does nothing to the buffer and returns EOF. 

Fseek(3S) erases all memory of inserted characters. 



SEE ALSO 



fseekr getc, setbuf 
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unlink 



RETURN VALUE 



Upon successful compLetioiif a value of is returned. Otherwise, a value 
of -1 is returned and ermo is set to indicate the error. 



SEE ALSO 
close, open 
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unlink 



unlink - remove directory entry 



SYNOPSIS 



int unlink (path) 
char *path; 



DESGRIETIC^ 



Unlink removes the directory entry named ty the path name pointed to be 
path. 

The named file is unlinked unless one or more of the following are true: 

A component of the path prefix is not a directory. [ENDTDIR] 

The named file does not exist. [ENOENT] 

Search permission is denied for a component of the path prefix. 
[EACCEIS] 

Write permission is denied on the directory containing the link to 
be removed. [EACCES] 

The named file is a directory. [EPERM] 

Bath points outside the process's allocated address space. [EFADLT] 

When all links to a file have been removed and no process has the file 
open, the space occupied ty the file is freed and the file ceases to 
exist. If one or more processes have the file open when the last link is 
renoved, the ronoval is postponed until all references to the file have 
been closed. 
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write 



Filc3es is not a valid file descriptor open for writing. [EBADF] 

If a _rite requests that more bytes be written than there is room for 
(e.g.f the physical end of a medium) , only as many bytes as there is roan 
for will be written. For example, suppose there is space for 20 bytes 
more in a file before reaching a limit. A write of 512 bytes will 
return 20. The next write of a non^zero number of bytes will give a 
failure return (except as noted belcw) . 



REIUI5N VALUE 

Upon successful completion the number of bytes actually written is 
returned. Otherwise, -1 is returned and ermo is set to indicate the 
error. 



SEE ALSO 



creat, dup, Iseek, open 
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write 



write - write on a file 



SYNOPSIS 



int write (f ildes, buf , nfcyte) 
int fildes; 
char *buf ; 
unsigned nbyte; 



DESCRIPTION 



Fildes is a file descriptor obtained from a create open, or dup syston 
call. 

Write attempts to write nbyte fcytes from the buffer pointed to by buf to 
the file associated with the fildes, 

On devices capable of seeking, the actual writing of data proceeds from 
the position in the file indicated by the file pointer. Upon return from 
write, the file pointer is incremented fcy the number of bytes actually 
written. 

On devices incapable of seeking, writing alw^s takes place starting at 
the current position. The value of a file pointer associated with such a 
device is undefined. 

If the 0_J^PEND flag of the file status flags is set, the file pointer 
will be set to the end of the file prior to each write. 

Write will fail and the file pointer will remain unchanged if one or more 
of the following are true: 
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yO 



y0f ylf ynr j0f 3I, jn, - Bessel functions 
SYNOPSIS 

OCC 06SS6>L 



y0-l 



yi 



mME 


yl, j0, jl. 


jn. 


yt3f 


yn - 


- BesseL 


functions 


SYNOPSIS 



See bessel 
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yn 



NZ^ME 


yn, j0r jlf 


JHf 


y0f 


yir 


- Bessel 


functions 


SYNOPSIS 



See bessel 
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Chapter 8 
WMCS Ccmpilation Conmands 



This chapter contains the four WMCS C compilation coiranands. They are 
formatted in the WMCS command-description style. If you are using C under 
WMCSr read these command descriptions. 

If you are using C under UniPlusf System V, see the cc conmand 
description in the UniPlus+ gystepi V UgQg's Reference Manual (Section H. 
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oonopile 



LL switches 



:iiiaxext= 
:ina2diash= 

:libraries= 

:prefix= 

rreloc 



:wamf66 
:xref= 

: runtimes 
: strip 



Parameters 



file list Function: Use this parameter to specify the list of files 

to be compiled and loaded together. 
Default : None, 

Syntax: Standard syntax for file lists. Wildcards are 
allowed. 



Switches 



:assenble 



:before= 



:case 



Function: Use this switch to specify that assenbly- 
language source files are to be assembled into object 
files. Assembly-language source files are files specified 
in the file list with a .S extension, plus any output 
files from the floating-point preprocessors. 
Default: :assembler i.e., assembly-language files are 
assenbled into object files. 

Syntax: Type :noassemble to suppress the assembler and 
the linker/loader phases. Files specified in the file 
list with a ,S extension are left untouched. Assonbly- 
language output files from the floating-point 
preprocessors are saved in the default directory with the 
same names as the corresponding source files, but with .S 
extensions. 

Function: Use this switch to select only those files that 

were specified in the file list and were created/modified 

before the specified date and time. 

Default: Selects all files that were specified in the 

file list. 

Syntax: Type :before= follcwed by a date and/or time in 

the standard date and time syntax. 

Function: Use this switch with FORTRAN source files to 
allow upper- and Icwer-case names to be distinct. 
Default: :nocase, i.e., upper- and Icwer^case names are 
not distinct. 

Syntax: Type :case to allow upper- and lower-case names 
to be distinct. 
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compile 



Description 



Use this ccmmand to compile C, FORTI^AN, and/or assonbly language 
source files into object files, and to link object files together to 
produce an executable file. 



Conmand Line 


Syntax 






MnenKDnic 


compile 






Required 
parameter 


File list 






Switches 


File selection 


:befor^= 

:exclude= 

:mod 


:since= 
:uic^ 




Suppress 
compilation 


: assemble 

:fpreprocess 

:load 


:preprocess 
: process 




General bitches 


rdeletetaiip 

:floatingpoint= 

:listing= 

:log 

:optimize 

:optimize= 


:output= 
:subopt= 
:subpass= 
rtemppref ix= 
: verbose 
:wamings 




C switches 


:define= 
: includes 


: undefined 




FORTRAN switches 


:case 
:int= 
:maxctl= 
:maxeqir= 


:maxstno= 
rone trip 
r range 
r undefined 
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OGnpiXe 

ifpreprocess 



: includes 



;int= 



;libraries= 



:listing= 



Function: Use this switch to specify that pseudo-assembly 
language source files are to be translated into actual 
assembly- language source files by a floating-point 
preprocessor. Pseudo-assonbly language source files are 
files specified in the file list with a .K extension, plus 
any output files from compilers and the C optimizer. The 
floating-point preprocessor used is selected by the 
: floatingpoints switch. 

Default: :fpreprocess, i.e., pseudo-assonbly language 
files are translated to actual assembly-language files, 
^ntax: Type :nofpreprocess to suppress the floating- 
point preprocessor, assembler, and linker/loader phases. 
Files specified in the file list with a .K extension will 
be optimized if the C optimizer is selected but will 
otherwise be left untouched. Pseudo-assonbly language 
output files fron the compilers and the C optimizer will 
be left in the current default directory with the same 
names as the corresponding source files, but with .K 
extensions. 

Function: Use this switch on C source files to specify 

additional directories in which the C preprocessor is to 

search for include files. Directories specified fcy the 

: includes switch are searched first, followed by 

predefined "standard" directories. 

Default: "The C preprocessor searchs only the predefined 

"standard" directories. 

Syntax: Type : includes followed fcy a list of directory 

specifications, separated fcy conmas. 

Function: Use this switch on FORTRAN source files to 
change the default size of FORTRAN integers. 
Default: :ints4, i.e., FORTRAN integers are 4 bytes long. 
Syntax: Type :ints followed by one of the following: 

2 Integers are 2 bytes long 
4 Integers are 4 bytes long 

Function: Use this switch to specify the names of library 

files to be used by the linker/loader in addition to the 

standard libraries. 

Default: Only the standard libraries are used. 

Siyntax: lype :librarieff= followed fcy a list of file 

names. Wildcards are not allowed. Device and directory 

names m^ not be given here but must instead be specified 

by the :pref ixs switch. 

Function: Use this switch to specify a file in which a 
program listing is generated. Currently, this switch 
applies only to FORTRAN. To get a listing from the 
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cxnpile 



:deletet€mp 



idefineF Function: Use this switch with C source files to define 
macros for the C preprocessor. Definitions given ty this 
switch can be cancelled by the :undefine= switch. 
Default: No macros are defined except some macros 
predefined ty the C preprocessor itself. 
Syntax: Type :define= followed ty a list of values, 
separated by commas. Each value must be in one of the 
following forms: 

nameF=value Assigns the value to the name 
name Assigns a value of 1 to the name 

Function: Use this switch to cause temporary files to be 
deleted automatically. 

Default: :deletetemp, i.e., temporary files, are 
automatically deleted. 

Syntax: Type :nodeletet3np to preserve temporary files. 

Function: Use this switch to select only those files or 

devices that were specified in the file list and do not 

match any of the files specified as the value of the 

:exclude= a/itch. 

Default: Selects all files or devices specified in the 

file list. 

Syntax: Type :exclude= followed ty a list of file or 

device designations, separated ty commas, any one of which 

may contain wildcard characters. 

:floatingpoint= Function: Use this switch to cause the compilers to 
generate code for a specific kind of floating-point 
hardware and/or software. This switch also selects the 
floating-point preprocessor to be used. 
Default: :floatingpoint=lib, i.e., the generic floating- 
point library is used. 

Syntax: Type :floatingpoint= followed ty one of the 
following : 



; excludes 



LIB Current version of the generic floating-point 

library (same as LIB2) . 
LIB2 Version 2 of the generic floating-point 

library. 
SKY Current version of the SKY floating-point 

board (same as SKYl) . 
SKYl Version 1 of the SKY floating-point board. 
FFP Current version of the FFP floating-point 

board (same as-FFPl). 
FFPl Version 1 of the FFP floating-point board. 
NOFP No floating-point (produces smaller image 

files) . 
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cfinpile 

:maxhash= 



:maxstno= 



:mod 



ronetrip 



:optimize 



:optiniiz( 



Function: Use this switch with FORERAN source files to 
specify the size of the FORTRAN compiler's symbol table. 
Default: :maxhash=401, i.e., the FORERAN compiler's 
symbol table has room for 401 entries. 

Syntax: Type :maxhash= followed fcy a numeral indicating 
the size of the FORTRAN compiler's symbol table. 

Function: Use this switch with FORERAN source files to 
specify the maximum number of statenent numbers allowed. 
Default: :maxstno=401 , i.e., a maximum of 401 statement 
numbers is allowed. 

Syntax: Type :maxstno= followed ty a numeral indicating 
the maximum nimber of statonent numbers to be allowed. 

Function: Use this switch to specify that the 
modification date is to be used in all date and time 
considerations ty the :before= or :since= switches. 
Default: :noimod, i.e., the creation date is used in all 
date and time considerations ty the :before= or :since= 
switches. 
Syntax: Type :mod. 

Function: Use this switch with FORERAN source files to 

specify that DO loops are to be executed at least once. 

Default: :noonetrip, i.e., DO loops are not performed if 

the upper limit is less than the lower limit. 

Syntax: Type :onetrip to cause DO loops to be executed at 

least once even if the upper limit is less than the lower 

limit. 

Function: Use this switch to perform code optimizations 

where possible. This switch has the same effect as 

:optimize=F77,OPE and is included for convenience. 

Default: :nooptimize, i.e., no optimizations are 

performed. 

Syntax: Type :optimize to perform optimizations. 

Function: Use this switch to perfom specific code 

optimizations. 

Default: No optimizations are performed. 

Syntax: lype :optimize= followed by one or both of the 

following values (if both, separate with commas) : 

F77 For FORTRAN source files only, performs FORTRAN- 
specif ic optimizations. 

OPE Performs optimizations on the pseudo-assembly 
language that is output from the compilers. This 
value is used for C programs. 
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assanbler use :subopt="as:-l filename" (where filename is 

the file you want to be the listing) . 

Default: A program listing is not generated. 

Syntax: Type :listings= followed by a file designation. 

Wildcards are not allowed. 



:load 



Function: Use this switch to specify that object files 

are to be linked to create an executable file. Object 

files are files specified in the file list with a .W 

extoision, plus any output files from the assonbler and 

LLC. 

Default: :loadr i.e., object files are linked to create 

an executable file. 

Syntax: Type :noload to suppress the linker/loader phase. 

Files specified in the file list with a .W extension are 

left untouched, and object files from the assembler and 

LLC are left in the current default directory with the 

same names as the corresponding source files, but with .W 

extensions. 



:log 



:maxctl= 



Function: Use this switch to specify whether log messages 
are displayed. (Log messages are informational displays 
that indicate what the utility is doing.) 
Default: The value specified by the OPTICN command. 
Syntax: Type :log or :nolog to override the default. 

Function: Use this switch with FORTE^AN source files to 

specify the maximum level that IF and DO statenents can be 

nested. 

Default: :maxctl=10, i.e., IF and DO statenents can be 

nested 10 deep. 

Syntax: Type :maxctl= followed by a numeral indicating 

the maximum number of levels that IF and DO statements can 

be nested. 



:maxeqiF= 



:maxext= 



Function: Use this switch with FORTRAN source files to 
specify the maximum number of equivalences allowed. 
Default: :maxequ=150, i.e., a maximum of 150 equivalences 
is allowed. 

Syntax: Type :maxequ= followed fcy a numeral indicating 
the maximum number of equivalences to be allowed. 

Function: Use this switch with FORTRAN source files to 
specify the maximum number of external symbols allowed. 
Default: :maxext=200, i.e., a maximum of 200 external 
symbols is allowed. 

Syntax: Type :maxext= followed ty a numeral indicating 
the maximum number of external symbols to be allowed. 
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:reLoc 



: runtimes 



:since= 



: strip 



performed at runtime. 

Default: morange, i.e., runtime range-checking of 

subscripts is not performed. 

Syntax: Type : range to cause runtime range-checking of 

subscripts to be performed. 

Function: Use this switch to specify that relocation 

information is to be preserved in the executable file. 

Default: :noreloc, i.e., relocation information is not 

preserved. 

Syntax: Type :reloc to cause relocation information to be 

preserved in the executable file (useful for unmapped 

S1250S) . 

Function: Use this S/fitdti to specify that the linker/ 
loader is to use language-specific runtime libraries. 
Default: The linker/loader automatically uses language- 
specific libraries whenever the corresponding language 
compiler is used. 

iSyntax: TyP^ :runtimeF followed by a value specifying a 
language-specific library. Currently, the only valid 
value is F, which specifies the FORERAN libraries. 

Function: Use this switch to select only those files 
specified in the file list and were created/modified since 
the specified date and time. 

Default: Selects all files specified in the file list. 
Syntax: lype :since= followed ty a date and/or time in 
the standard syntax. 

Function: Use this switch to specify that all symbols are 
to be stripped from the executable file. 
Default: :strip, i.e., all symbols are stripped. 
Syntax: TyP® :nostrip to preserve symbols in the 
executable file. 



:subpas&= Function: Use this switch to specify substitute compiler 

passes. The ccmpile utility uses a three-step algorithm 
to determine the filename of each compiler pass. First, 
compiler passes specified ty the :subpass= switch are 
used. Second, for passes not specified ty the :subpass= 
switch, passes specified by logical names are used. 
Finally, for passes not specified ty the :subpass switch 
or ty logical names, the standard compiler passes are 
used. 

Default: If any of the following logical names are 
defined, then their definition is used as the filename of 
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Function: Use this switch to name the output file of the 
compilation process. 

Default: If :preprocess, :nofpreprocesSf :noasse5nble, or 
:noload is specified, the output is stored in the default 
directory in files with the same names as the 
corresponding source files specified in the file list, but 
with extensions of .1, .K, .S, or .W respectively. If the 
linker/loader phase is not suppressed, the resulting 
executable file is stored in the default directory with 
the same name as the first file specified in the file 
list, but with an extension of .EXE. 

Syntax: lype :output= followed ty a file name without a 
file extension. The correct extension (.1, .S, or .EXE, 
for example) is added automatically fcy the compiler. 
Wildcards are not allowed. 



prefix= Function: Use this switch to specify additional 
directories in which the linker/loader is to search for 
libraries. Directories specified by the :pre£ix= switch 
are searched first, followed ty predefined "standard" 
directories. 

Default: The linker/loader searchs only the predefined 
"standard" directories. 

Syntax: Type :prefix= followed ty a list of directory 
specifications, separated by commas. As a special case, a 
value of zero causes the predefined "standard" directories 
to not be searched. 



:preprocess 



:process 



: range 



Function: Use this a/itch to specify that the output from 

the preprocessors is to be left in the current default 

directory in files with the same name as the corresponding 

source files, but with .1 extensions. All other phases of 

the compile are suppressed. 

Default: :nopreprocess, i.e., preprocessor output is sent 

to the compilers, and other phases of the compile compile 

are not suppressed. 

Syntax: Type :preprocess to send the output of the 

preprocessors to .1 files. 

Function: Use this switch to specify that the output from 

the preprocessors is to be sent to standard output. All 

other phases, of the compile are suppressed. 

Default: :noprocess, i.e., preprocessor output is not 

sent to standard output, and other phases of the compile 

are not suppressed. 

Syntax: Type : process to send the output of the 

preprocessors to standard output. 

Function: Use this switch with FORTRAN source files to 
specify that range-checking of array subscripts is to be 
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Syntax: Type :uic= followed fcy a list of UIC's or 
user names. 

:undef ine= Function: Use this switch with C source files to "cancel 

macro definitions for the C preprocessor given fcy the 
:define= switch. Ihis switch can also be used to cancel 
the macros predefined by the C preprocessor itself. 
Default: No macros are cancelled. 

Syntax: Type :undefine= followed by a list of names, 
separated by commas r to be cancelled. 

: undefined Function: Use this switch with FORTRAN source files to 

specify that the default type of variables is undefined, 
rather than using the default FORTRAN rules. 
Default: :noundef ined, i.e., the default type of 
variables is determined according the default FORTRAN 
rules. 

Syntax: Type : undefined to cause the default type of 
FORTRAN variables to be undefined. 



rverbose 



:warnf66 



rwamings 



:xref= 



Function: Use this Sf/itch to display the command line for 

each compiler pass before it is executed. This switch 

also sets the :log switch. Additional information may be 

displayed as well depending on the situation. 

Default: :noverbose, i.e., command lines for compiler 

passes are not displayed. 

Syntax: Type : verbose to display command lines for each 

compiler pass. 

Function: Use this switch with FORTRAN source files to 

suppress extensions that enhance compatibility with 

F0RrRAN66. 

Default: :nowarnf66, i.e., extensions that enhance 

FORrRAN66 compatibility are not suppressed. 

Syntax: Type :wamf66 to suppress extensions that enhance 

FORTRAN66 ccmpatibility. 

Function: Use this switch to display warning messages 
generated by the compiler. 

Default: :wamings, i.e., warning messages are displayed. 
Syntax: Type :ncwarnings to suppress warnings. 

Function: Use this switch with FORERAN source files to 
specify a file in which a symbol cross reference listing 
is generated. 

Default: A cross-reference listing is not generated. 
Sjyntax: Type :xref= followed by a filename. Wildcards are 
not allowed. 
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the corresponcaing ccmpiler pass, otherwise the standard 
compiler passes are used: 

Name Corresponding Ccmpiler Pass 



CPP C preprocessor 

F77 FORTRAN compiler 

F77X FORTRAN cross reference 

CC C compiler 

OPT C optimizer 

APP Floating-point preprocessor 

AS Assembler 

LLC Compiler for linker/loader 

LL Linker/loader 

Syntax: Type :subpas&= followed ty one or more values, 
separated by commas , in the form name:f ilename, where name 
is one of the names given in the above table, and filename 
is the filename (including its directory) of the 
corresponding substitute compiler pass. 

:subopt= Function: Use this switch to specif arbitrary command 

line arguments for individual compiler passes. (This 
switch is provided for maximum flexibility. Take care not 
to misuse it.) 

Default: Only arguments put on the command line ty 
COMPILE (possibly determined ty regular COMPILE switches) 
are passed to the compiler passes. 

Syntax: lype one or more values, separated by commas, 
where each value is of the form "name: string". The name 
must be one of the following: CPP, F77, F77x, CC, OPT, 
APP, AS, LLC, or LL (see :subpass= for the meaning of each 
name) . The string is the actual string to be placed on the 
named compiler pass's command line. If the string contains 
spaces, then the entire name: string value should be 
enclosed in double quotes. 

:t€mpprefix= Function: Use this switch to specify the directory in 
which temporary files are stored. 

Default: If the logical name TMPDIR is defined, then the 
directory it specifies is used, otherwise the directory 
SYS^EMP/SYSIMP/ is used. 

Syntax: Type :tempprefix= followed by a directory 
specification. Wildcards are not allowed. 

:uic?= Function: Use this ^vitch to select only those files or 

devices that are specified in the file list and are owned 
by the specified user or list of users. 
Default: Selects all files specified in the file list. 
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At first glance, the :runtiin6= switch might appear useless 
since language-specific libraries are automatically 
included whenever the corresponding language compiler is 
used. This could be used if you previously compiled 
several FORTBMH source files into objects and now want to 
link these object files together to produce an executable 
file. Compile would only see a bunch of .W files and 
wouldn't knew about their FORTRAN ancestry. You would 
have to use the :runtime= switch to explicitly tell 
COMPILE that these object files were produced fran FORTRAN 
source files and require the use of the FORTRAN libraries. 

In order to produce smaller executable files, the symbol 
table is normally stripped ty the linker/loader. When 
debugging programs with WIBUG, however, it is highly 
recommended that you use inostrip to preserve the symbols. 



Related CIP Commands 



lllib 
11 ran 
li 
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Examples 

> compile inain.Crroutinel.c,routine2,c 

This ooinmand compiles the C source files named MAIN.Cf 
ROUTINEl.Cr and RajriNE2.C in the default directory, 
producing the object files MAIN.W, RCUTINEl.W, and 
Ra7riNE2.W, and the executable file MAIN. EXE. 

> compile *.f :prefix=/iiYlib/ :lib=matrix :float?=slcy :output=munge.exe 

Assume that the library file /MYLIB/MATRIX.LIB exists on 
the default device. Iliis command compiles all of the 
PORIRAN source files with a .F extension in the default 
directory, producing a .W object file for each one. These 
object files are then linked together using the library 
file /MYLIB/MATRIX.LIB to produce an executable file named 
MJN3E.EXE. The program is targeted for the SKY floating- 
point board. 

Using Prompts 



> Compile 

File list > main.c, routinel.c, routine2.c 

lliis is the same as the first example. 



Notes on Usage 



The :optimize and :optimize= switches improve the ultimate 
efficiency of the program, but compilation usually takes 
longer. 

Any of the five switches that suppress compilation phases 
may be specified at the same time. The switch that comes 
first in the following list is used, and any other 
switches in the list that are specified are ignored: 

: process 
:preprocess 
:nof pr eprocess 
moassemble 
moload 
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Switches 



:before= - lype a c3ate and time, (see dates) 

:exclude= - lype a list of file designations, (see f ilelist) 

:log - Log messages are displayed. 

:mod - Use file modification date for comparison 

:since= - lype a date and time, (see dates) 

:uiG= - Type a list of uics or usemames. (see uiclist) 

rverbose - Display detailed information about the files. 

The following switches are mutually exclusive: 

:add - Add the files to the library. Create library. 

: delete - Delete the indicated files from the library. 

:extract - Extract the indicated files from the library. 

:list - List the files in the library. 
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Description 



Use this ccmmand to create or maintain a packaged library file for the 
11 loader. The indicated relocatable object files generated by WiJ^C 
are archived into a file, and llran is used to generate a symbol 
table. 



Examples 



> Illib develop. lib *.w :add :log 

Generate the library file develop. lib from all the .w files in the 
current directory. Display the names of the files being libraried. 



Parameters 



Library file > - Required. Enter the name of the library file to be 

used. A file extension of .lib is customary. 

File list > - Optional. Type a list of file designations which 

are to be displayed, added, or deleted. Wildcards 
are only permitted when adding. Default: With :add, 
all files in the current directory, with : extract 
or :list, all files in the library, with : delete, 
no files. 
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Display fonnat 

:filename 

: header 
: pause 
:radix= 



:segment= 



:sort= 



: truncate 



Precede each symbol by the name of the file 

it is in 

(Default) Display filename and column headers 

Pause after each screenful of display 

Select the base in which symbol values are 

displ^ed. 

Specify one of the following: octal, decimal, 

or hexadecimal. Default: hexadecimal. 

Select which segnents to display. Specify one 

or more of the following (separated by 

commas): all, , absolute, text, data, stack, 

uoonstant, sconstant, or unknown. 

Default: all. 

Select the order symbols are displayed. 

Specify one of the following: name, value, 

none. 

Default: name. 

(Default) Truncates symbol names in the 

display if they are longer than the display 

field width. 
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Description 



Use this conmand to display symbols in image files (.EXE files) 
generated ty the LL linker. 



Examples 



> li 

Display all symbols in all image files in the current directory. (Non- 
image files are ignored. Image files generated by the LINK linker will 
always have "no symbols found" as will stripped LL image files.) 



Parameters: 



File list >- Optional. Default: *. Type a list of file 

designations whose symbols are to be displayed, 
(see f ilelist) 



Switches 



File selection 

:beforeF= - lype a date and time, (see dates) 

: excludes - T^pe a list of file designations, (see 

filelist) 
:mod - Use file modification date for comparison 

:since= - l^pe a date and time, (see dates) 
:uio= - lype a list of uics or usernames. (see 

uiclist) 
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Description 



Use this conmand to create or maintain a packaged library file for the 
11 loader. The indicated relocatable object files generated by WiMC 
are archived into the file SYMTAB.LL in the current directory. 



Example: 



> Ilran *.w :log 

Generate the directory library file SYMTAB.LL in the current directory 
from all the .w files in the current directory. Display the names of 
the files being libraried. 



Parameters: 



File list > - Required. Type a list of file designations whose 

attributes are to be displayed or modified, (see 
f ilelist) . 



Switches 



:before= 

:exclude= 

:log 

:mod 

:quick 

:since= 

:uic?= 

:verbose 

:warnings 



lype a" date and time, (see dates) 

lype a list of file designations, (see f ilelist) 

Log messages are displayed 

Use file modification date for comparison 

Allow or disallcw scrutinizing the input 

lype a date and time, (see dates) 

lype a list of uics or usernames. (see uiclist) 

Display detailed information about files 

Allcw or disallcw warning messages 
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Calling Functions Written in Other Languages 

The function return value is stored in register d0. If the return value 
is of type double, then the most significant half of it is in d0. The 
least significant half of^ it is in dl. 

C and fORII»N77 

To write C-language procedures that call or are called ty FORTRAN??, it 
is necessary to knew procedure names, data representation, return values, 
and argument lists that the compiled code uses. 

Procedure Names 

The name of a FORTE^AN procedure has an underscore added to it ty the 
compiler. The underscore distinguishes the procedure name from a C- 
language procedure or external variable with the same user-assigned 
name. 

Also, FOKERAN-library procedure names have embedded underscores to 
avoid clashes with user-assigned subroutine names. 

Data Representation 

The following is a list of corresponding FORTRAN and C declarations: 

FORTRAN C Language 

integer *2 x short int x; 

integer x long int x; 

logical x long int x; 

real x float x; 

double precision x double x; 

complex X struct { float r, i; } x; 

double complex x struct {double dr, di; } x; 

character*6 x char x[6]; 

Integer, logical, and real data occupy the same amount of memory in 
FORTRAN, 

Return Values 

A function of type integer, logical, real, or double precision 
declared as a C function returns the corresponding type, A complex 
or double complex function is equivalent to a C routine with an 
additional initial argument that points to the place where the 
return value is to be stored. 
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Chapter 9 
Calling Functions Written in Other Languages 



The calling function evaluates each actual parameter and pushes it on the 
stack f rem right to left. 

The following type conversions are performed on each actual parameter 
value before it is pushed: 

1. A float is converted to a double. 

2. A char or short is converted to an int. 

3. An unsigned char or unsigned short is converted to an unsigned 
int. 

4. An array name is considered a pointer to the first element in the 
array. 

5. A entire struct or union is pushed on the stack. Structs and 
unions can be very large. Everything on the stack gets pushed. It 
may have an extra dummy tyte added to the eid so an even number 
of bytes is always pushed. 

After the parameters have been pushed, the caller calls the function. The 
C compiler adds an underscore to the beginning of function names. 

The called function preserves registers 62 through d7 and a2 through a7. 
Registers d0, dl, a0, and al are not preserved. These four registers are 
called scratch registers. 

Once the called function has returned, the parameters are popped off the 
stack. 

NOTE: The caller pops the parameters from the stack. This is helpful 
with functions that have a variable number of parameters (such 
as printfO) because the caller knows how many parameters to 
pop. 
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The string lengths are long int quantities passed ty value. 
The arguments are in the following order: 

1. Extra arguments for cxmpLex and character functions 

2. Address for each datum or function 

3. A long int for each character argument 

Because of this, the call in 

external f 
character*? s 
integer b(3) 

• • • 

call sam(f, b(2) ,s) 

is equivalent to the call in the following: 

int f(); 
char s[7]; 
long int b[3]; 

• • • 
sam_(f,&b[l] ,s,7L); 

NOTE: The first element of a C array alw^s has subscript 0, 

However, FOPTEIAN arrays begin at 1 by default, PORIKAN 
arrays are stored in column-major order. C arrays are 
stored in row-major order. 

C and Bascal 

C functions cannot call Pascal routines because of unresolvable 
differences between the C and Bascal calling conventions. However, C 
functions can be called ty Pascal routines because the Pascal compiler 
generates C style calls through the cexternal directive. Also, external C 
variables are not accessible fran Pascal. 

Limitations 

The C library and the Pascal runtime library are not compatible. Ihe 
C memory allocation routines (malloc, etc.) conflict with the Pascal 
memory allocation routines (mark, new, etc.). 

Since mar^ library routines allocate monory internally, it is 
difficult to tell what will work and what won't. 
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Because of this, the following: 

complex function f (...) 

is equivalent to 

struct { float r, i;} temp; 
f__(&tenp,...) 

A character-valued function is equivaleit to a C routine with two 
extra initial arguments, a data address and a length. Therefore, 

character *15 function g(...) 

is equivalent to the following: 

char result [] ; 

long int length; 

g_( result, loigth, . . . ) 

... 

The foregoing could be invoked in C by the following: 

char chars [15]; 

... 

g_(chars,15L, ...); 

Subroutines are invoked as if they are integer-valued functions, 
whose value specifies which alternate return to use. Alternate 
return arguments (statanent labels) are not passed to the function. 
They are used to do an indexed branch in the calling procedure. 

The return value is undefined if the subroutine has no entry points 
with alternate return arguments. 

The statemoit 

call nret(*l, *2, *3) 

is treated exactly as if it were the computed goto 

goto (1, 2, 3) , nretO 

Argument Lists 

All FORTRAN arguments are passed ty address. In addition, for every 
argument that is of type character, an argument giving the length of 
the value is passed. 
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C enumerated types are always 4 bytes long. The^ do not 
correspond to Pascal enumerated types. 

(3) Manber of the Pascal set corresponds to the least significant 
bit of the C unsigned char. Member 1 corresponds to the next 
significant bit. 

(4) Member of the Pascal set corresponds to the least significant 
bit of the first C unsigned long int. Monber 63 corresponds to 
the inost significant bit of the last unsigned long int. 

Return Values 

To be called from Pascal, a C function should be of type int, long 
int, unsigned int, unsigned long int, double, pointer, or void. 

A C function of type void corresponds to a Pascal procedure. 

Argument Lists 

To be called from Pascal, a C function should not have formal 
parameters of type float, struct, or union. In addition, the Pascal 
compiler does not account for the type conversions listed in this 
chapter. Therefore, a C formal parameter of type char or short 
corresponds to a Pascal actual parameter of type longint. 

Array parameters work as long as subscripting is declared to begin 
at in Pascal. 
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In addition^ some routines in each library depend on initializations 
done by the main program. Jf the main program is written in C, the 
Pascal initializations aren't done. If the main program is written 
in Pascal, the C initializations aroi't done. 

Therefore, you can write C functions to be called ty Pascal 
routines, but you do so at your cwn risk. 

The cexternal directive exists primarily so that Pascal can access 
UNIX systan calls. 

If you want to try to call C functions with Pascal routines, the 
following information may be of help. 

To be called from Pascal, the name of the C function must not 
contain any uppercase letters. Pascal is not case sensitive. It 
assumes that the names of all C functions are in lowercase. 

Furthermore, a C function called foo must be declared as _^oo in 
Pascal. The C compiler puts a leading underscore on function names, 
but Pascal does not. 

Data Rep resentations 

Following is a list of corresponding Pascal and C declarations: 

Pascal C Notes 



x: 


: char; 


unsigned char x; 




XJ 


boolean; 


char x; 


(1) 


x: 


: integer; 


short int x; 




x: 


: longint; 


long int x; or int x; 




x; 


: (red, green, blue); 


unsigned char x; 


(2) 


x: 


: real; 


double x; 




XJ 


: record i, j: integer end; 


struct {short int i, j;} 


x; 


X. 


: string [9]; 


char x[10]; 




x: 


: array [0..9] of char; 


char x[9] ; 




x: 


: "ohar; 


char *x; 




X 


: set of 0..1; 


unsigned char x; 


(3) 


X 


: set of 0..63; - 


unsigned long int x[2]; 


(4) 



(1) False corresponds to 0, true corresponds to 1 (in most cases, 
true corresponds to any value other than 0) . 

(2) Red corresponds to 0, green corresponds to 1, and blue 
corresponds to 2. Pascal enumerated types are 1 tyte long if 
they have 256 values or less. Otherwise they are 2 bytes long. 



9-5 



Debugging 

can be changed tanporarily to ronove the static modifier for 
debugging, 

Autg variables (and formal parameters) 

Auto variables also have no symbols. Because an auto is a local 
variable, it is usually easier to find a nearty reference to it 
than to a static variable. 

An auto variable's location can be estimated. An auto variable 
is located at a negative offset from register a6. Generally, 
the C compiler places the first auto variable nearest a6, the 
next auto further from a6, etc, 

A formal parameter is accessed like an auto variable is 
accessed except it is located at a positive offset frcm a6. 

Register variables 

Register variables have no symbols, but, like auto variables, 
references to them can often be found in the code (see chapter 
3 for details) 

Also, it is possible to determine the hard/are register that 
corresponds to a given register variable in functions that have 
not been optimized (see chapter 3 for details) . 

A register parameter is like a register variable except that an 
initial value gets copied into the register at the beginning of 
the function. 

Hcnir to Locate Code 

Locating ^ f unctjQn 

Non-static functions are referred to ty name. The name is 
preceded ty an underscore. The name represents the address of 
the first instruction in the function. 

Static functions cannot be referred to by name. Like static 
variables, a static function can best be located ty finding a 
reference to it in the code, then noting its address. 

Locating lines in ^ f unct j.pn 

If the C optimizer is not used, specific lines in a function 
can be located ty examining the .s assonbly language source 
file produced by the G compiler. 
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Chapter 10 
Debugging 



The WMCS debugger is WIBUG. The UniPlus+ System V debugger is adb. Both 
are symbolic assenbly-level debuggers, that is, th^ allow functions and 
variables to be accessed by name at the assembly-language level. 

For detailed inf onnation on WIBUG see the WIBUG Programmer's Reference 

For detailed information on adb see the UniPlusf System ]£ User's Manual 
(Section 1). 

Because WIBOS and adb have roughly equivaloit capabilities, they will be 
referred to in this chapter as WIBUG/adb. 

Hov to Locate Data 

External variables can be referred to by name. However, static, auto, and 
register variables have no symbols with which they can be accessed, 
Following are tips for accessing each storage class: 

External variables 

An external variable can be referred to by its name, preceded 
by an underscore. 

For example, a global variable called foo in C is called _foo 
in WIBUG/adb. The symbol represents the address of the first 
byte of the variable. WIBUG/adb can locate the variable, but 
has no information about its type or size. 

Static variables 

Static variables have no symbols, and their location in memory 
is hard to predict. A static variable is best found by locating 
a reference to it in the code, and then noting its address. It 
is also possible to declare all statics with a macro so they 
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the optimizer performs live/dead analysis on then. A simple' 
change in the C source can result in a drastic change in the 
optimized assembly code. 

The optimizer ronoves the LINK and UNLK instructions from a 
function if it has no non-register local variables. Ihis causes 
parameters to be at an unpredictable offset fran the stack 
pointer, rather than at a predictable offset from register a6. 

Stack backtraces in WIBUG/adb depend on the linked list of 
stack frames maintained ky the LINK and UNLK instructions. 
Backtraces of optimized code can be misleading because 
functions without LINK and UNLK do not appear in the backtrace. 

The optimizer remaps register variables to registers with lower 
numbers. Ihis takes advantage of unused scratch registers. 
Ranapping makes it more difficult to calculate which hardware 
register corresponds to which register variable. 
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To produce a .s file under WMCS, use the compile canmand with 
the moassemble switch. To produce a .s file under UniPlus+ 
system V, use the ££ canmand with the -S option. 

Source file names and line numbers are indicated fcy .line and 
.file directives among the assembly-language statanents. 

The beginning of the C source file and each #include file is 
marked by a .file directive in the following format: 

.file filejiumber, "file_name" 

In the foregoing fonnat, filejiumber is a unique integer and 
file_name is the name of the source file. The end of each 
#include file is marked ty an abbreviated .file directive in 
which the file name is omitted, and the file number is the 
number of the file that did the #include. 

The beginning of each C statonent is marked by a .line 
directive in the following format: 

. 1 ine 1 ine_jiumber 

In the foregoing format , line_jiumber is the number of the line 
on which the statonent begins. 

A .line directive appears only for lines containing the 
beginning of a statement. 

Lines containing only comments, declarations , etc. are not 
represented. 

Debugging Optimized Code 

Debugging code that has been optimized with the C optimizer is 
difficult. Your ability to debug optimized code depends on the 
optimizations that were performed. 

Following are some things to watch out for: 

The C optimizer ronoves all .file and .line directives. It does 
this because it moves, eliminates, and rearranges code, 
invalidating the line numbers. To locate lines in a function, 
you must look at the assonbly code and try to correlate it with 
the source manually. 

However, the optimized assonbly code may not correspond in an 
obvious way to the original C source. The code for a C 
statonent could be dispersed, or eliminated altogether. This is 
most likely to occur with the use of register variables because 
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Abbreviations for control key functions: 



NUL 


- Null 


DCl 


- Device control 1 


SCH 


- Start of header 


DC2 


- Device control 2 


STX 


- Start of text 


DCS 


- Device control 3 


ETX 


- End of text 


DC4 


- Device control 4 


EOT 


- End of transmission 


NAK 


" Negative acknowledge 


ENQ 


- Enquiry 


SYN 


- Synchronous idle 


ACK 


- Acknowledge 


L'TB 


- End of transmission block 


BEL 


- Bell 


CAN 


- Cancel 


BS 


- Backspace 


EM 


- End of medium 


HT 


- Horizontal tab 


SUB 


- Substitute 


LP 


- Line feed 


ESC 


- Escape 


VT 


- Vertical tab 


FS 


- File separator 


FF 


- Form feed 


GS 


- Group separator 


CR 


- Carriage return 


PS 


- Record separator 


SO 


- Shift out 


US 


- Unit separator 


SI 


- Shift in 


SP 


- Space 


DLE 


- Data link escape 


DET. 


- Delete 
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Character 


DEC 


HEX 


Char DEC 


HEX 


Char DEC 


HEX 


Char DEC 


HEX 


[CrRL]@ NUL 


000 


00 


SP 


032 


20 


@ 


064 


40 


\ 


096 


60 


[CTRL] a SOE 


001 


01 


! 


033 


21 


A 


065 


41 


a 


097 


61 


[CTRLJb STX 


002 


02 


II 


034 


22 


B 


066 


42 


b 


098 


62 


[CTRLJc ETX 


003 


03 


# 


035 


23 


C 


067 


43 


c 


099 


63 


[CTRLjd EOT 


004 


04 


$ 


036 


24 


D 


068 


44 


d 


100 


64 


[CTHLle ENQ 


005 


05 


% 


037 


25 


E 


069 


45 


e 


101 


65 


[CTRL]f ACK 


006 


06 


& 


038 


26 


F 


070 


46 


f 


102 


66 


[CrRL]g BEL 


007 


07 


1 


039 


27 


G 


071 


47 


g 


103 


61 


[CTRL J h BS 


008 


08 


( 


040 


28 


H 


072 


48 


h 


104 


6Q 


[Ci'RLli HT 


009 


09 


) 


041 


29 


I 


073 


49 


i 


105 


69 


[CrRL]j LP 


010 


OA 


• 


042 


2A 


J 


074 


4A 


j 


106 


6A 


[CrRL]k VT 


Oil 


OB 


+ 


043 


2R 


K 


075 


4B 


k 


107 


6B 


[CTRLll FF 


012 


OC 


r 


044 


2C 


L 


076 


4C 


1 


108 


6C 


[Cn?L]in CR 


013 


OD 


- 


045 


2D 


M 


077 


4D 


m 


109 


6D 


[CTRLln SO 


014 


OE 


• 


046 


7E 


N 


078 


4E 


n 


110 


6E 


[Ci'RLjo SI 


015 


OF 


/ 


047 


2F 





079 


4F 


o 


ni 


6F 


[Ci'RLlp DLE 


016 


10 





048 


30 


P 


080 


50 


P 


112 


70 


[Ci'RLlq DCl 


017 


11 


1 


049 


31 


Q 


081 


51 


q 


113 


71 


[CTRL]r DC2 


018 


12 


2 


050 


32 


R 


082 


52 


r 


114 


72 


[CTKL]s DC3 


019 


13 


3 


051 


33 


S 


083 


53 


s 


115 


73 


[CTRL]t DC4 


020 


14 


4 


052 


34 


T 


084 


54 


t 


116 


74 


[CTRLJu NAK 


021 


15 


5 


053 


35 


U 


085 


55 


u 


117 


75 


[CTKLjv SYN 


022 


16 


6 


054 


36 


V 


086 


56 


V 


118 


76 


[CTRL]w ETTB 


023 


17 


7 


055 


37 


W 


087 


57 


w 


119 


77 


[CIKLlx CAN 


024 


18 


8 


056 


38 


X 


088 


58 


X 


120 


78 


[Ci'KLly EM 


025 


19 


9 


057 


39 


Y 


089 


59 


y 


121 


79 


[CTRLlz SOB 


026 


lA 


• 
• 


058 


3A 


Z 


090 


5A 


z 


122 


7A 


[CTRL] [ ESC 


027 


IB 


/ 


059 


3B 


[ 


091 


5B 


{ 


123 


7B 


[CERL]\ PS 


028 


IC 


< 


060 


3C 


\ 


092 


5C 


1 


124 


7C 


[CTRL]] GS 


029 


ID 


= 


061 


3D 


] 


093 


5D 


} 


125 


7D 


[CrHL]" RS 


030 


IE 


> 


062 


3E 


A 


094 


5E 


"• 


126 


7E 


[CERL]_ US 


031 


IF 


• 


063 


3F 


— 


095 


5F 


DEL 


127 


7F 
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14 Are any additional characters allowed in an identifier? No 
additional characters are allowed in identifiers (only 
letters, digits, and the underscore, _, are allowed) . 

16 Are enum and void impLemented? Yes, both are impLemented, 

16 Is entry a reserved word? No. 

16 What are the reserved words in WICAT Systens C? The reserved 
words are listed in appendix C of this manual. 

17 Are the digits 8 and 9 allowed as octal digits? Yes, but a 
warning message is generated. 

17 What are the storage sizes of the data types? The storage 
sizes are given in chapter 3. 

18 How are out-of- range values handled? Constants larger than 
MAXINT (2147483647) are silently truncated, and no warning or 
error message is generated. 

19 What representation does the 68000 use for integers? The 
twol complement representation is used for integers. 

21 How is the char constant in^emented? Character constants 
are implonoited as 8-bit signed types, i.e., the sign 
extends. 

23 How is the backslash treated when it is followed by an 
invalid escape code? The backslash, \, is ignored when it is 
followed by an invalid escape-code character. 

25 Is hexadecimal notation allowed in numeric escape codes? 
Yes. The hexadecimal escape code \pc is allowed in character 
constants (e.g., "\xlA") . 

26 Can the preprocessor and the compiler be operated 
separately? Yes. The compilation process is described in 
chapter 2. 

27 Are the preprocessor ooimnands tellf and defined supported? 
The preprocessor command defined is supported but Jeiif. is 
not. 

28 Is leading space and whitespace allowed with the macro 
commands? No leading space, whitespace yes. 

33 Can actual argument token lists extend across multiple 
lines? Backslash required. 
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Si:?)pl€inQit to £l A Reference IfeimL 



The book £i t Reference Manual supplied ty WICAT Systans raises questions 
about differences between various inpLementations of C. Ihis appendix 
clarifies those questions so that £i ^ Reference Mnual/. along with this 
appendix, is a complete language referoice for WIC3^T Systems C. These 
answers are given in the order tiie questions are presented in the book. 

9 Does the character set include additional characters not in 
the standard set Yes. WIC3VT supports the complete ASQI 
character set (e.g., the $, §, and ^ characters are 
included) . The characters not included in the standard set 
can only appear in comments, character constants, or string 
constants. 

10 What is the line limit of a C program? 256 characters. 
Different parts of the software generation system have 
different line limits. The shortest limit is 256 characters 
for the floating-point preprocessor. 

12 Are nested comments allowed? Nested comments are accepted. 

However, lint generates a warning message for nested 
comments. 

14 What is the maximtm length of an identifier? Identifiers of 

any length are allowed. However, global and static 
identifiers are declared in the assembly output on one line, 
similar to this: 

.global <identifier> 

The Qitire line must be less than 256 characters to work with 
the floating-point preprocessor, so the practical limit to 
the iQigth of an identifier is about 200 characters. 
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The call aONC(INC,TAB) is ultimately e2q>anded into this: 

tafcil e_of _incr ement s 

40 Does the preprocessor perform stringent error checicing? The 
preprocessor does not check for things such as an incomplete 
token in the macro definition. 

40 Hew are double quotes and angle brackets treated in #include 
statements? Files listed in double quotes are only searched 
for in the directory the source is in. Files listed in angle 
brackets are searched for in the standard directories and any 
other directories specified with compiler options. The 
directories you specify are searched first. 

41 What are the standard include directories? The standard 
include directories are: 

/usr/ include (UNIX only) 
sys$disk/ucc. include/ (WMCS only) 
sys$disk/sysincl.sys/ (WMCS only) 

41 Are nested #include statanents allcwed? Yes. Nesting is 
allowed to 16 levels. 

46 Hew are errors in constant egressions in preprocessor 
conditional oonnnands handled? when an error occurs in a 
constant e:q)ressionr no warning message is generated and the 
value is assumed to be zero. 

48 Is # allowed for #line? Yes. The line "# <number>" is the 
same as "#line <number>" 
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34 Are macro formal parameters reoognized within string and 

character constants? Yes. Formal parameters will have the 
same textual form as the actual parameters when expanded with 
the exception that oommoits are deleted. Ebr example, 
consider the definition and call below: 

#define X{x) "x" 

X( a += 00400 /* foo blat */ ) 

The definition would cause the call to expand to this 
constant: 

" a += 00400 " 

34 How are comments within macros treated? They are not passed 

when a macro definition is substituted (see the example in 
the foregoing comment) . 

36 What areWICAT's predefined macros? The only predefined 

macros are: 

mc68000 

Unix (for UNIX systems) 

wmcs (for future WMCS systens) 

36 How is an attempt to redefine a macro handled? Macros can be 
redefined. The new definition replaces the old one, and the 
preprocessor generates a warning message, including warnings 
about parameter mismatches. 

37 Are macro definitions implemented with a stack? No. The 
preprocessor does not stack macro definitions (defined with 
#def ine) . X would not be defined as 10 after the following 
three commands, as the example on p. 37; x would be 
undefined: 

#def ine x 10 
#def ine x 12 
#undef 

39 Are macro bodies treated as character sequences? Yes. 
Consider the following example, given on p. 39. of the text: 

#def ine INC ++ 

#def ine TAB inter nal_table 

#def ine INCTAB tahle_of_incranents 

tdefine a»IC(x,y) x/**/y 

GONC(INC,TAB) 
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74 Is compile-tiine floating point arithmetic performed? Yes. 

75 Are casts allowed in constant expressions? Yes. 

76 Can autcmatic arr^s be Initialized? No. 

77 Are braces allowed in enumeration initialization 
expressions? Yes. 

78 Can bit fields be initialized? Yes, static and extern bit 
fields can be initialized. 

79 Can unions be initialized? No. 

80 Are too few or too many braces allowed in initializer lists? 

No. WICAT Systems C strictly oonforms to the "Brace Eliding" 
rules given on p. 79 of the text. 

80 Are pointers and ints the same size? Yes. Chapter 3 lists 
the storage size for each data type. 

81 Whoi is a top-le/el declaration of an external name 
considered to be its definition? The compiler uses the 
"mixed" strategy , described on p. 82 of the text, to define 
external names. With an initializer but no extern, it is a 
definition. With no initializer and no extern, it is a 
"common" definition. If extern is there, the definition 
occurs elsewhere. 

87 What are the sizes of short, int, and long? The sizes for 
all data types are given in chapter 3 of this manual. 

89 What unsigned types are supported? The compiler supports 
unsigned long, short, and char types. 

90 Hew is the char type implemented? The char type is signed. 
Therefore it can assume negative values. The size of char, 
along with the sizes of all data types, is given in chapter 3 
of this manual. 

93 Is long float allowed? No, the compiler does not recognize 
"long float" as a synonym for double. 

98 f9hat is the maximum dimension of an array? The compiler can 
handle up to 13 dimensions of an array. In general, the 
compiler can handle 13 levels of indirection. 

99 What is the unit of measuronent returned ty the sizeof 
operator? The sizeof operator returns the size of an array 
in ]sits&. 
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54 Are labels placed in the same space as variables? No. 

Labels have a separate name space from variables. In this 
example, given on p. 54, the integer declaration of L hides 
the label (it is not an illegal duplicate definition of L) : 

{ ... 



got 


L; 


• • • 
{ 


int L; 




... 

{ ... 

L = 10; 




... 

L: 




• . • 

} 



} 

56 Hew are forward references to static variables handled? 
Forward references to static variables with "extern" do not 
change the storage class of the variable, i.e., it remains 
static. 

59 Are the normal scoping rules different for external 
declarations? Yes. Ihe normal scoping rules for extern 
declarations are "violated." The following example, given on 
p. 59, extends the definition of E to the second assignment 
(it is not illegal): 

{ 

{ 

extern E; 
E = 0; 

} 

E = 1; 

} 

61 Hew mary register variables are available? The use of 

register variables is described in chapter 3 of this manual. 

69 Are zero-length arrays allowed? No, but null-sized arrays 

are allowed, evai in some contexts where it does not seen to 
make sense. For example, the following function compiles even 
though it is improper: 

funcO { 

char carray[] ; 
sprintf (carray, ...); 

} 
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156 Can the address operator be used with a register variable? 
No, you cannot take the address of a register variable, 

157 Can the address operator be used with an array or function? 
The compiler generates a warning message if you try to take 
the address of an array or a function. 

163 Hew is integer division with negative numbers handled? In 
integer division involving negative numbers where the 
mathematical quotient is not an exact integer, the result is 
the nearest integer which is closest to zero (i.e., the same 
as for positive numbers) • 

169 Hew does the signed ri^t shift work? Right shifts of signed 
numbers replicate the sign bit, i.e., the sign bit is 
extended. 

183 Can the result of a conditional e^^ression be structure, 
union, enumeration, or void? Yes, any of them. 

185 Are structure and union assignments allowed? Yes. 

186 Is whitespace allowed between the characters of a compound 
assignment operator? Yes. For example, "i + = 5" is 
allowed. 

187 Are the "old style" compound assignment operators 
recognized? The "old style" compound assignment operators 
described on pp. 186-187 are recognized and generate a fatal 
error. Statements like "i=-4" produce warning messages about 
ambiguous assignments. 

189 Is the exclamation point, i, allowed in constant 
expressions? Yes. 

190 Is casting allowed in constant expressions? Yes. 

190 la the oonima operator allo/ed in constant expreeaiona? No. 

193 Is a warning message generated for discarded values? No. 

194 Does the compiler optimize memory access? No. 

216 Are the enum and long types allowed in switch statements? 
Yes. 
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102 What is the size of an enum type? The size of all data types 
is given in chapter 3 of this manual. 

102 Can previously defined enum constants be used in enum 
constant expressions? Yes. 

103 Hew is the enum type Implanented? The enumeration type is 
implemoited as an integer model. 

106 What structure operations are possible? Structures can be 
assigned, passed as parameters, and returned as function 
values. 

108 Can two structures have components with the same name? Yes, 
the overloading of structure component names is allowed. 

108 Hew are structure components packed? Structure components 
larger than the size of char always start at an even-byte 
offset. 

109 Hew are bit fields packed? Bit fields are packed from left 
to right. 

110 Hew are bit fields in^emented? Bit fields must be unsigned 
(int or enum type) . Signed declarations produce no warnings 
or errors and are treated as though unsigned. Fields are 
limited to 32 bits (one longword) . Fields too large to fit 
entirely in the curreit longword are aligned to the next word 
boundary. Zero-length bit fields are not supported. 

140 Hew are overflew, underflow, division-by-zero, and other 
arithmetic exceptions handled? Overflew, underflow, and 
other arithmetic exceptions do not generate error or warning 
messages. The (unpredictable) results are propagated through 
future results. Division by zero, however, generates an 
error message. 

145 Does enclosing an e:q>ression in parentheses force a unary 
conversion? No. 

148 Can functions return structures and unions? Yes. 

150 Can formal parameters be used in a function ej^ression? No, 
you cannot specify a formal parameter declared as being of 
type "function returning T" for some type T. 

153 Are "narrowing casts" performed ty the compiler? Yes. 

154 What is the type of the sizeof result? The result type of 
the sizeof operator is unsigned int. Ihe size is given in 
bytes. 
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The keyword (reserved word) list for WIQ^T's C compiler conforms to the 
proposed ANSI standard for C. 

If you use a keyword as an identifier, the compiler returns a syntax 
error. 

Following is a list of the keywords for the WIGAT C compiler. The words 
followed by an asterisk are reserved due to the proposed standard: 



asm 


enum* 


struct 


auto 


for 


sizeof 


break 


float 


short 


char 


fortran 


static 


case 


goto 


typedef 


const* 


if 


unsigned 


continue 


int 


union 


double 


long 


void* 


default 


return 


vol at i 1 e* 


do 


register 


while 


extern 


signed* 




else 


switch 
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lllib, 7-1 

llran, 7-1 
OOTipile prooessr 

diagrams, 2-2 

UniELus+ Systen V, 2-2 

WMCS, 2-2 
compiler, featuresr 3-7 
compiler limitationsr 2-3 
compiler optimizationf 4-4 

cx^mmon tail merging, 4-5 

constant folding, 4-1 

dead code elimination, 4-4 

elimination of stack pops, 4-8 

input, 4-1 

instructions, 4-2 

link/UNLK removal, 4-7 

loop rotation, 4-6 

NOP suppression, 4-8 

peephole optimizations, 4-9 

redundant branch elimination, 4-5 

register remapping, 4-6 

strength reduction, 4-2 

type reductions, 4-2 

unreachable code elimination, 4-4 
cos, see trig 
oosh, see sinh 
creat, creat-1 
crypt, crypt-1 
ctermid, ctermid-1 
ctime, ctime-1 
ctype, ctype-1 
cuserid, cuserid-1 

data registers, 3-4 
a0=l, d0, dl, 3-4 
a2-a5, d2-d7, 3-4 
a6, 3-4 
a7 (sp), 3-4 
data types, storage sizes, 3-2 
debugging, 10-1 
adb, 10-1 
locating code, 

function, 10-2 

lines in a function, 10-2 
locating data, 10-1 
auto variables (and formal 
parameters) , 10-2 

external variables, 10-1 

register variables, 10-2 



static variables, 10-1 
optimized code, 10-3 
things to watch out for, 10-3 
assembly code, 10-3 
file and .line, 10-3 
LINK/UNLK, 10-4 

ronapping register variables, 10-4 
stack backtraces, 10-4 
WIBU3, 10-1 
drand48, drand48-l 
dup, dup-1 

ecvt, ecvt-1 

erand48, see drand48 

erf, erf-1 

erf c, see erf 

ermo, see perror 

exec, exec-1 

execl, see exec 

execle, see exec 

execlp, see exec 

executable files and images 

format, 3-2 

execv, see exec 

execve, see exec 

execvp, see exec 

exit, exit-1, 

exp, exp-1 

fabs, see floor 
fdose, fclose-1 
f cvt, see ecvt 
f dopen, see f open 
feof , see f error 
f error, ferror-1 
fflush, see fclose 
f getc, see getc 
fgets, see gets 
fileax), see f error 
floating-point , 
C optimizer, 5-3 
choosing preprocessor, 5-2 
compiler, 5-1 
debugging, 5-7 

a move, 5-7 

cc -K, 5-7 

compile : nofpreprocess, 5-7 

jsr, 5-7 

under UniPlus+ System V, 5-8 
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a641, a641-l 

abs, abs-1 

acsosr see trig 

adb, 10-1 

ASCII character tabler A-1 

asijif see trig 

assembler optimizationr 4-10 

branch shortening, 4-10 

on 68000, 4-11 

span-dependent optimizationr 4-10 
atan, see trig 
atan2, see trig 

besselr bessel-1 
brkr brk-1 
bsearchf bsearch-1 

.c extaision, 2-1 
C libraries, 6-1 

files under Unillus+ System V, 6-1 

files under WMCS, 6-1 

Id, 6-1 

LL, 6-1 
C program hard/are limitations, 2-3 

process size, 2-3 



c source files, 2-1 
calling P0RERAN77, 9-2 

argument lists, 9-4 

C and FORERAN declarations, 9-2 

procedure names, 9-2 

return values, 9-3 
calling function, 9-1 
calling Pascal, 9-4 

argument lists, 9-6 

C and Pascal declarations, 9-5 

data representations, 9-5 

limitations, 9-5 

procedure names, 9-5 

return values, 9-6 
calloc, see malloc 
cc, 2-1 

ceil, see floor 
dtidir, chdir-1 
chmod, chmod-1 
clear err, see f error 
dose, dose-l 
compilation under WMGS, 

compile, 7-1 

li, 7-1 
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lrand48, see drand48 
Isearch, lsearch-1 
Iseekr lseek-1 
ltQl3, see 13tol 

malloCf malloc-l 
math library, 6-2 

under UniPlus+ System V, 6-2 

under WMCS, 6-2 
memccpyf see memory 
memchr/ see memory 
mencmpf see memory 
memc^f see memory 
memory, memory-1 
memset, see memory 
mktempf mktanp-l 
modf , see frexp 
mrand48r see drand48 

nrand48, see drand48 
NULL pointer, misuse, 2-3 

open, open-1 

optimization, definition, 4-1 
optimization cautions, 4-20 
optimization tricks, 4-14 

CMPM instruction, 4-15 

DBRA instructions, 4-15 

fast data copying/comparison, 4-18 
improving array access and 
pointer arithmetic, 4-16 
optimizing functions with more 
register variables than 
registers, 4-14 
post-increment and pre- 
decrement addressing, 4-15 

speeding up arithmetic functions, 4-16 
optimizer optimization, 4-3 

basic blocks, 4-3 

data collection techniques, 4-3 
flew analysis, 4-3 
live dead analysis, 4-4 

fundamental units, 4-3 

module, 4-3 

moving window, 4-3 

perror, perror-1 
pow, see exp 
printf, printf-1 



putc, putc-1 
putchar, see putc 
puts, puts-1 
putw, see putc 

qsort, qsort-1 

rand, rand-1 

realloc, see malloc 

register-indirect-with-offset 

addressing mode, limitations, 

2-3 

rewind, see f seek 

scanf, scanf-1 

seed48, see drand48 

setbuf, setbuf-1 

setjn^), setjmp-1 

setvbuf , see setbuf 

sin, see trig 

sinh, sinh-1 

sleep, sleep-1 

software generation system, 2-1 

getting good code, 4-11 
sprintf , see printf 
sqrt, see exp 
srand, see rand 
srand48, see drand48 
sscanf , see scanf 
stack, 3-5 
Stat, stat-1 
storage, 

auto, 3-1 

external, 3-1 

register, 3-2 

static, 3-1 
storage allocation example, 3-6 

calling function, 3-6 

local array, 3-6 

register variables, 3-6 

static variable, 3-6 
strcat, see string 
strchr, see string 
strcmp, see string 
strc^, see string 
strcspn, see string 
string, string-1 
strlen, see string 
stmcat, see string 
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under WMCS, 5-8 
breakpoint, 5-8 
libraries, 5-8 
startups, 5-8 
symbols, 5-8 
double storage format diagram, 5-4 
exception handling, 5-6 
divide-by-zero, 5-6 
illegal operation, 5-6 
overflew, 5-6 

under Unillus+ System V, 5-6 
under WMCS, 5-7 
underflow, 5-6 
float storage format diagram, 5-4 
hardware and software, 5-1 
libraries, 

under UniPlus+ Syston V, 5-9 
under WMCS, 5-9 
precision, 5-3 
registers, 5-3 
reserved values, 5-5 
software enulation, 5-1 
under UniFlus+ System V, 5-2 
under WMCS, 5-2 
fpmgr command, 5-2 
floor, fLoor-l 
flood, see floor 
fopen, fopen-1 
fprintf , see printf 
fpukc, see putc 
fputs, see puts 
fread, fread-1 
free, see malloc 
f reopen, see fopen 
frexp, frexp-1 
fscanf , see scanf 
fseek, fseek-1 
f Stat, see stat 
ftell, see fseek 
function call stack frame, 
local variables, 3-5 
register variables, 3-5 
function call stack frame 
diagram, 3-5 
function parameter, 3-5 
fwrite, see fread 

gamma, gamma-1 
gcvt, see ecvt 



getc, getc-1 
getchar, see getc 
geto/d, getcwd-1 
getgid, see getuid 
getlogin, getlogin-1 
getopt, getopt-1 
getpgrp, see getpid 
getpid, getpid-1 
getppid, see getpid 
gets, gets-1 
getuid, getuid-1 
getw, see getc 

hcreate, see hsearch 
hdestroy, see hsearch 
hsearch, hsearch-1 
hypot, hypot-1 

Initialized external and static 
variables, 3-4 
isalnum, see ctype 

L, see ctype 

., see ctype 
see ttyname 

,, see ctype 

:, see ctype 

L, see ctype 

', see ctype 

;, see ctype 

;, see ctype 

I, see ctype 

', see ctype 



isalpha, 

isasciii 

isatty, 

iscntrli 

isdigit, 

isgraph, 

islcwer. 

ispcintj 

ispuncti 

isspacei 

isupper^ 

isxdigit, see ctype 

j0, see bessel 
jl, see bessel 
jn, see bessel 
jrand48, see drand48 

keywords, C-1 
reserved, C-1 

13tol, 13tol-l 
164a, see a641 
laong48, see drand48 
lde3^, see frexp 
log, see exp 
Xogl0, see exp 
longjmp, see set j rap 
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WICAT Systems, Inc. 

Product-documentation Comment Fomi 

We are constantly improving our documentation, and we welcome specific comments on this manual. 
Document Title: 



Part Number: 



Your Position: D Novice user D System manager 

D Experienced user D Systems analyst 

a Applications programmer Q Hardware technician 

Questions and Comments Page Na 

Briefly describe examples, illustrations, or information that you think should be added 
to this manual. 



What would you delete from the manual and why? 



What areas need greater emphasis? 



List any terms or symbols used incorrectly. 



Rfst f=bld 
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